Version 11.2

Web Services Guide

Web Services Guide

Product version: 11.2

Release date: 10-22-15

Document identifier: WebServicesGuide1603081515

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.

Web Services Guide iii

Table of Contents

1. Creating and Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Creating Custom Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

JAX-RPC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Automatic Generation of Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Session and Security Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Method Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Web Service Creation Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Anatomy of a Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Web Service Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Deploying Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Managing Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Creating JMS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Using the JMS Message Web Service Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Structure of a JMS Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Patch Bay Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Creating Repository Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Using the Repository Web Service Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Repository Web Service Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Modifying Repository Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

RepositoryService Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Repository to XML Data Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Mapping Files and XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Repository Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Accessing Web Services from Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

About Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Before You Begin Using a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Writing a CookieContainer Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Calling Web Services from a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Creating a Serializer and Deserializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Accessing Web Services from .NET Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

About Web Services in the Oracle Commerce Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Before You Begin Using a .NET Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Calling Web Services from a .NET Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Using the Atg.DotNet.WebService API with RepositoryItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

2. Introduction to REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

REST Web Services Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

REST Web Services URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

HTTP Request Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Returning Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Using cURL for Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Writing cURL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Server Response to cURL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

cURL Command Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Adding Control Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Functional Parameters for Oracle Commerce Platform REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Using Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Using URL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Using Message Body Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

I. Oracle Commerce Platform REST MVC Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

iv Web Services Guide

3. Installing and Configuring the REST MVC Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Installing the REST MVC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Enabling REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Using Dynamo Session Confirmation Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

4. The REST MVC Definition Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

REST MVC Service Flow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Actor Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Request URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

XML Definition Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

The Actor-Template Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

The Actor-Chain Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

The Actor Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

The Component Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

The Droplet Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

The Form Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

The JSP Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

The Output Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

The Input Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

The Depends and Depends-If-Present Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

The Set Variable Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Actor XML Definition File Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Working with Implicit Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Combining Actor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Bean Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

The Bean Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

The Filter Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

The Property Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

The Attribute Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

The Repository Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

The Item-Descriptor Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Working with Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Configuring REST MVC Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

REST MVC Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Example: External User Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Example: Internal User Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Creating a New REST MVC Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

5. External REST MVC Service Call Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

External Service Call Workflow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Getting the Session Confirmation Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Specifying Site Context in a Multisite Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Working with Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Logging In Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Logging Out Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Creating New Customer Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Editing or Updating a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Viewing a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Viewing the Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Working with the Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Adding Multiple Items to the Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Adding an Item to a Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Updating the Shopping Cart by SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Updating the Shopping Cart by Commerce ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Web Services Guide v

Updating the Shopping Cart By Shipping Group Relationship ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Removing and Adding an Item to the Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Removing an Item From the Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Removing an Item From the Shopping Cart By Relationship ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Starting the Checkout Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Working with the Shipping Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Displaying Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Specifying the Default Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Applying the Default Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Obtaining the Current Shipping Info List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Applying Shipping Groups and Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Splitting Commerce Items into Different Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Displaying Available Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Creating a New Hardgood Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Editing a Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Working with the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Display the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Specifying the Default Payment Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Applying Default Payment Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Obtaining Current Payment Info Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Applying Multiple Payment Groups to an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Creating a New Credit Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Updating a Credit Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Working with Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Identifying if Fractional Quantities Are Allowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Getting the User’s Current Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Browsing the Catalog By Category ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Browsing the Catalog by Product ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Browsing the Catalog by SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Return Product Prices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Return Product Summary Prices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Getting Product Prices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Getting Lowest and Highest Prices for a Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Getting List Price and Sale Prices for a SKU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Working with Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Looking Up an Order by Order ID or User ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Cancelling or Deleting an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Saving an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Claiming a Coupon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Confirming an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Committing an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Sending Order Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Obtaining Closeness Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Working with Returns and Exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Initiating a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Selecting Items to Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Getting Return Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Confirming a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Displaying Return Confirmation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Canceling a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Returning Refund Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Applying Non-Default Refund Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Identifying Returnable Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

vi Web Services Guide

Viewing Details of Returned Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Reviewing Return History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Showing Non-Return Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Identifying if an Order is Part of an Active Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Updating Credit Cards for a Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

Displaying Lost Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Working with Gift Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Creating a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Updating a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Adding Items to a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Adding Items to a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Removing Items from a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Removing Items from a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Moving Items to a Gift or Wish List from a Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Deleting a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Viewing the Current Profile’s List of Gift Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Viewing a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Viewing a Gift List’s Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Viewing a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Searching for a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Working with In-Store Pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Searching for a Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Displaying Search Results for In-Store Pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Identifying a State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

6. Internal REST MVC Service Call Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Internal REST MVC Service Calls Workflow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Getting the Session Confirmation Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Logging Agents In and Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Logging In Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Logging Out Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Confirming Log Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Changing Agents Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Setting Default Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Restoring Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Working with Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Starting a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Ending a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Adding a Call Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Working with Tickets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Selecting a Ticket to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Creating a New Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Saving a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Associating a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Escalating a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Closing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Releasing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Deferring a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Reassigning a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Sending a Ticket to a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Closing a Ticket as Duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Editing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

End Editing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Viewing Active Tickets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Web Services Guide vii

Looking Up a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Searching for a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Reviewing a Ticket Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Viewing a Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Working with Customer Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Creating a New Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Updating an Existing Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Adding a Note to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Searching for a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Clearing a Customer Search Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Selecting a Customer to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Working with Customer Profile Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Adding an Address to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Editing an Address in a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Deleting an Address from a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Working with Credit Cards Within a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Adding a Credit Card to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Editing a Credit Card in a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Deleting a Credit Card from a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Viewing a Customer’s Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Working with a Customer’s Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Adding Multiple Items to a Customer’s Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Adding Items to a Customer’s Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Updating the Customer’s Shopping Cart by SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Updating the Customer’s Shopping Cart by Commerce ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Updating the Customer’s Shopping Cart By Shipping Group Relationship ID . . . . . . . . . . . . . . . . 222

Removing and Adding an Item to the Customer’s Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Removing an Item From the Customer’s Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Removing an Item From a Customer’s Shopping Cart By Relationship ID . . . . . . . . . . . . . . . . . . . . 223

Starting the Checkout Process with SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Starting the Checkout Process with Commerce ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Starting the Checkout Process with Relationship ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Changing the SKU of an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Assisting the Customer with the Shipping Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Displaying Available Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Specifying a Single Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Specifying Multiple Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Splitting Items into Different Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Applying Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Displaying All Available Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Creating New Hardgood Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Editing a Hardgood Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Obtaining the Customer’s Current Shipping Info List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Assisting the Customer with the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Display the Customer’s Payment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Getting Available Payment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Claiming Store Credit or a Gift Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Claiming a Customer’s Coupon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Applying Multiple Payment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Working with Credit Cards Within an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Getting a Customer’s Existing Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Adding a Credit Card to an Existing Address in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Adding a Credit Card to a New Address in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

viii Web Services Guide

Updating a Credit Card in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Assisting Customers with Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Creating New Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Viewing the Current or Active Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Viewing the Customer Order History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Searching and Clearing Searches for an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Finding an Order by Order ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Selecting an Order to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Cancelling or Deleting the Current Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Viewing Cross Sell Items in a Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Saving or Committing an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Confirming a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Sending a Customer Order Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Modifying a Submitted Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Submitting a Modified Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Duplicating an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Adding a Note to a Customer’s Current Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Adding a Note to a Customer’s Original Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Creating a Quote for a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Working with Scheduled Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Creating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Updating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Submitting a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Activating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Deactivating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Displaying Scheduled Order Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Displaying Scheduled Order Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Working with Scheduled Order Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Creating a Template from a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Validating a Scheduled Order Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Sending E-Mail Confirmation for a Scheduled Order Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Identifying a Template Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Reviewing a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Viewing a Template Order List of Submitted Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Viewing a User’s List of Template Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Adjusting Customer’s Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Adjusting a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Deleting an Adjustment from a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Overriding an Item’s Price in the Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Viewing the Adjustment Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Viewing the Reason Code for an Adjustment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Assisting Customers with Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Getting the Customer’s Current Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Browsing the Customer’s Catalog By Category ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Browsing the Customer’s Catalog By Product ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Searching for Catalogs with Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Working with the Current Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Obtaining Product Prices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Getting Price Ranges for a Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Obtaining List Price and Sale Prices for a Product by SKU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Working with Customer’s Price Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Selecting a Current Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Retrieving the Current Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Web Services Guide ix

Resetting the Current Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Searching for a Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Working with Customer’s Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Getting Available Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Updating Prices After Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Adding a Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Removing a Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Include Promotions from Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Ignoring Promotions from Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Saving the Promotions Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Reverting the Promotions Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Obtaining Closeness Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Searching for Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Adding Store Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Displaying Lost Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Displaying Changed Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Working with Customer’s Gift Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Creating a Customer’s Gift or Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Updating a Customer’s Gift or Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Adding Items to a Customer’s Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Adding Items to a Customer’s Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Removing Items from a Customer’s Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Removing Items from a Customer’s Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Moving Items to a Gift or Wish List from a Customer’s Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . 286

Deleting a Customer’s Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Viewing a Customer’s Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Viewing a Customer’s Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Searching for a Customer’s Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Viewing a List of Customer’s Gift or Wish Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Assisting Customers with In-Store Pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Working with Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Finding Pending Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Approving or Rejecting a Pending Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Assisting the Customer with Returns and Exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Returns and Exchange Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Creating a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Adding Items to a Return Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Obtaining Return Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Confirming a Return Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Displaying Return Request Confirmation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Cancelling a Return Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Receiving Return Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Retrieving Available Refund Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Applying Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Displaying Return History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Identifying if the Order is Returnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Identifying if an Item is Returnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Identifying if the Order Contains an Active Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Reviewing Details of Returned Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Displaying Non-Return Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Updating a Credit Card for a Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Applying Appeasements to a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Initiating an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

x Web Services Guide

Applying an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Validating an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Submitting an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Cancelling an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Sending a Confirmation Message for an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Approving an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Rejecting an Appeasement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Modifying Refund Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Modify a Refund Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Resetting a Refund Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Responding to Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Sending a Customer E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Adding an Attachment to an E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Discarding an E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Sending Customer E-Mail and Closing Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Working with the Commerce Service Center Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Obtaining Global Session Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Listing Available Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Selecting a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Viewing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Working with Ticket Disposition Warnings and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

II. Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

7. Using Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

HTTP Requests for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Nucleus Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Handling POST Requests as Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Logging In as an External User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Logging In as an Internal User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Functional Parameters for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Input Values in Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Returned Data in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Choosing Output Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

JSON Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

XML Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Identifying a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Multiple Values in Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Return Depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Date Format in Returned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Errors and Exceptions in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Problems Performing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Problems Processing a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Working with Legacy REST Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Getting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Setting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Invoking Legacy REST Component Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Invoking Legacy REST Form Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

Submitting Legacy REST Form Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Returning Legacy REST Form Handler Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

Web Services Guide xi

Returning Legacy REST Form Handler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

Legacy REST Form Value Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Invoking Java Server Pages (JSPs) with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Legacy REST Web Services JSP Configuration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

URL Templates for Legacy REST Web Services JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Configuring the Legacy REST Service Processor Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Example Legacy REST Web Services JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Working with Repositories in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Listing Repository Items in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Retrieving a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Retrieving a Specific Property Using Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Performing RQL Queries in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Adding a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

Transient Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

Setting Repository Item Properties in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

Deleting a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

Property Filtering with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Default Filtering in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Filtering Templates with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Filtering for One Request with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

Property Aliasing with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

Suppressing Property Expansion in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

Filtering Priority in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

Configuring the Legacy REST Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373

/atg/rest/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

/atg/rest/processor/BeanProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

/atg/rest/output/JSONOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

/atg/rest/output/XMLOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

/atg/rest/processor/RepositoryProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

/atg/rest/processor/RestSecurityProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Security for Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Legacy REST Security Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

Quick Setup for Testing Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Global Security with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Component Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Property and Method Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

Repository Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Securing Groups of Components in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

8. Legacy Rest Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Java Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Creating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Creating a RestSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

Starting a REST Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

Logging in and Logging Out with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Starting a Session Without Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Accessing Data from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Creating a Raw REST Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

Handling Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Accessing Components with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

Calling Methods with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

Accessing Repository Items with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Using the Java Client in Android Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

ActionScript Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

xii Web Services Guide

atg.rest.client.RestComponentHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

atg.rest.client.RestRepositoryHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Calling Methods with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

Formatting Input with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

1 Creating and Using Web Services 1

1 Creating and Using Web Services

A common requirement for enterprise applications is the ability to share data and business logic with other

applications. For example, suppose you have an employee portal built with the Oracle Commerce Platform,

and also a payroll system based on some other software package. When a new employee starts, or an existing

employee changes his or her marital status, you need to create or modify the employee’s profile in both systems.

Ideally, you’d like the employee to be able to make the changes in one application and have those changes

automatically propagate to the other application.

One way to address this issue is through Web Services, a widely supported standard for packaging remote

procedure calls in an XML-based structure. In the example above, you could create a Web Service that

automatically updates an employee’s profile in the employee portal when the information in the payroll system

is modified.

The Dynamo Application Framework includes tools that allow you to create custom Web Services that call

methods on Nucleus components. These custom Web Services can expose methods on existing Oracle

Commerce Platform Nucleus components, or on Nucleus components you write yourself. You can call these Web

Services from an external application client, such as the payroll system mentioned above.

The Oracle Commerce Platform packages Web Services as: J2EE applications, in accordance with the JAX-RPC

(JSR 101) and Implementing Enterprise Web Services (JSR 109) specifications. Note that this manual assumes

that you’re familiar with these specifications, and with Web Services in general. For more information about

these specifications, see the Java Community Process Web site at:

http://www.jcp.org

The following sections discuss how to create Web Services in the Oracle Commerce Platform, and how to write

Java and .NET clients that call these services:

Creating Custom Web Services (page 4)

Creating JMS Web Services (page 15)

Creating Repository Web Services (page 18)

Repository to XML Data Binding (page 21)

Accessing Web Services from Java Clients (page 35)

Accessing Web Services from .NET Clients (page 44)

2 1 Creating and Using Web Services

Web Services

In addition to any Web Services you create, the Oracle Commerce Platform includes a number of prepackaged

Web Services that you can call from Java and .NET clients. These services are packaged in three separate

application modules. You can include any of these services in an assembled EAR file by including the module

that contains the desired services. For example, to include the prepackaged Oracle Commerce Core Commerce

Web Services, specify the DCS.WebServices module when you assemble your application.

The following table summarizes these Web Services.

Note: The following services are available in DAS.WebServices. For more information about these Web

Services, see the Repository Guide.

Web Application Web Services

Generic Repository Services getRepositoryItem

performRQLQuery

performRQLCountQuery

The following services are available in DPS.WebServices. For more information about these Web Services, see

the Personalization Programming Guide.

Web Application Web Services

User Session loginUser

logoutUser

getProfileId

setLocale

setContactInfo

setPassword

getProfile

createUser

updateUser

getPasswordHashKey

getPasswordHashAlgorithm

canClientEncryptPasswords

executeRepositoryTargeter

Messaging sendPageVisit

sendClickThrough

The following services are available in DCS.WebServices. For more information about these Web Services, see

Core Commerce Programming Guide.

1 Creating and Using Web Services 3

Web Application Web Services

Order createOrderFromXML

submitOrderWithReprice

cancelOrder

getOrderStatus

getOrderAsXML

getOrdersAsXML

getOrderStatus

getCurrentOrderId

addItemToOrder

addItemToShippingGroup

createOrder

createOrderForUser

removeItemFromOrder

setItemQuantity

addCreditCardToOrder

addShippingAddressOrder

removePaymentGroupFromOrder

removeCreditCardFromOrder

removeShippingGroupFromOrder

moveItemBetweenShippingGroups

removeItemQuantityFromShippingGroup

setOrderAmountToPaymenGroup

getDefaultPaymentGroupId

getDefaultShippingGroupId

Pricing calculateOrderPrice

calculateOrderPriceSummary

calculateItemPriceSummary

Promotions grantPromotion

revokePromotion

claimCoupon

getPromotionsAsXML

Inventory getInventory

getInventoryStatus

setStockLevel

setStockLevels

Catalog getProductXMLById

getProductXMLByDescription

getProductXMLByRQL

getProductSkusXML

catalogItemViewed

Profile setDefaultShippingAddress

setDefaultBillingAddress

setDefaultCreditCard

getDefaultShippingAddress

getDefaultBillingAddress

getDefaultCreditCard

4 1 Creating and Using Web Services

Creating Custom Web Services

The Oracle Commerce Platform provides infrastructure and tools that enable you to expose a wide range of

functionality as Web Services. There are three kinds of Web Services you can create:

• Web Services that invoke methods on Nucleus components

• Web Services that send JMS messages through Patch Bay

• Web Services that perform operations on repository items

This section describes the infrastructure for creating these services. It focuses on Web Services that invoke

Nucleus methods, but most of what is described here applies to all three types of services. For information

specific to Web Services that send JMS messages, see the Creating JMS Web Services (page 15) section.

For information specific to Web Services that perform repository operations, see the Creating Repository Web

Services (page 18) section.

This section includes the following:

Web Service Creation Wizard (page 5)

Anatomy of a Web Service (page 7)

Web Service Security (page 12)

Deploying Web Services (page 13)

Managing Web Services (page 14)

JAX-RPC Support

The Web Services support in the Oracle Commerce Platform is based on JAX-RPC (Java API for XML-based RPC).

The JAX-RPC specification defines a standard way for incoming XML-based SOAP messages to be converted to

Java-based RPC calls. The Oracle Commerce Platform uses Oracle’s reference implementation of JAX-RPC. Parts

of this reference implementation are used to generate Web Services, and other parts of it handle the processing

of SOAP messages when a Web Service is called.

Automatic Generation of Web Services

Creating a Web Service by hand can be a laborious process, due to the large number of Java and XML files you

must create and package. The Oracle Commerce Platform automates this process through the Web Service

Creation Wizard in the Dynamo Administration UI. You select the type of service you want to generate, and

the wizard takes you through a series of screens where you specify the necessary information. You then click

a button, and the wizard automatically generates the necessary classes, WSDL documents, and deployment

descriptors, and packages them in EAR and WAR files.

Session and Security Support

When you create a Web Service, you specify whether it should be executed within the context of an HTTP

session. Associating Web Services with a session enables an application to maintain state across Web Service

calls and to use login information for security purposes.

1 Creating and Using Web Services 5

To enable multiple Web Services to execute within the same session, a client application must pass a session

cookie between calls. Some Web Services frameworks, such as Microsoft’s .NET, provide support for passing

session cookies. Java clients typically require applications to manage session cookies themselves.

For more information about using sessions with Java clients, see the Accessing Web Services from Java

Clients (page 35) section. For more information about using sessions with .NET clients, see the Accessing Web

Services from .NET Clients (page 44) section.

Method Limitations

You can create Web Services from most Nucleus methods, both from components Oracle Commerce Platform

provides and components that you write. There are, however, some methods that cannot be exposed as valid

Web Services. The Web Service Creation Wizard does not create Web Services from these methods. In particular,

it enforces the following restrictions by preventing you from selecting these methods:

• You cannot create a Web Service from any method that has a parameter or return type that is an abstract data

type (such as a Map, Collection, Interface, abstract class, or an object with abstract data type properties)

• You cannot create a Web Service from any method that has a parameter or return type that is a wrapper class

for a primitive data type. The prohibited classes are Byte, Boolean, Character, Integer, Short, Long,

Float, and Double. Note, however, that methods that use actual primitives are valid. If there is a method that

you want to expose that has one of these wrapper classes as a parameter or return type, you can either rewrite

the method to use a primitive instead (if the method’s class is your own custom code), or else subclass the

method’s class (if it is a class provided by Oracle Commerce Platform) and overload the method with a version

that uses primitives

In addition, you cannot create a Web Service from a method that has the same name and signature as any of

the methods of atg.webservice.ManagedComponentProperties or java.lang.Object. Attempting to

do so results in a naming conflict, because the service implementation class of each Web Service subclasses

atg.webservice.ManagedComponentProperties, which subclasses java.lang.Object. Note that the

wizard does not prevent you from selecting these methods, but when you try to generate a Web Service, an

exception is thrown and the service generation fails.

Web Service Creation Wizard

The process of creating Web Services is automated by the Web Service Creation Wizard in the Dynamo

Administration UI. This wizard guides you through the steps of selecting a Nucleus component and method,

specifying input parameters and other settings; it then automatically creates the Web Service by performing the

following steps:

• Create the service endpoint interface that specifies the method to be exposed

• Create the service endpoint class that implements the service endpoint interface and is responsible for

handing incoming SOAP requests

• Create the WSDL document that describes the resources required by the service endpoint class, as well as its

inputs and outputs

• Create the web.xml file for the Web application of which the service is a part

• Create the JAX-RPC deployment descriptor (webservices.xml) and mapping file

• Build the runtime classes

6 1 Creating and Using Web Services

• Package these elements in a JSR 109 compliant EAR file

These steps are described in more detail in the Anatomy of a Web Service (page 7) section.

The wizard uses the component /atg/webservice/WebServiceGenerator to perform the actual work of

generating the service. This component, which is of class atg.webservice.

WebServiceGeneratorImpl, performs all of the operations listed above, either through its own methods or

through other components it refers to.

Using the Wizard

The top-level page of the Dynamo Administration UI includes a Web Service Administration link. This link takes

you to the Web Service Administration page, which has three links for working with Web Services:

• Web Service Registry – Takes you to a page for viewing and managing currently loaded Web Services. The

Web Services registry is discussed in the section Managing Web Services (page 14)

• Web Service Security Manager – Enables you to create and edit Web Service security configurations. These

security configurations can be used to define which users can access specific Web Services. When you

create a Web Service, you have the option of associating a security configuration with the service. Security

configurations are discussed in the section Web Service Security (page 12)

• Web Service Creation Wizard – Takes you to a page with links for creating each of the three kinds of Web

Services (Component Method Web Service, JMS Message Web Service, Repository Web Service)

To create a Web Service that invokes a method on a Nucleus component, starting from the Web Service

Administration page:

1. Click the Web Service Creation Wizard link. This takes you to a page titled Select Type, where you can select

the type of Web Service to create.

2. Click the Component Method Web Service link. This takes you to the Select Nucleus Component page.

3. On the Select Nucleus Component page, specify the pathname of the Nucleus component you want to create

the Web Service from. You can either enter the pathname directly in the field at the top of the page and then

click the Next button, or you can use the component browser below it to navigate to the component and

select it.

4. On the Select A Method page, select the method you want to expose as a Web Service.

5. If the method requires any input parameters, the Set Parameter Names page provides you with fields for

specifying the names of these parameters. The names you specify are used for the parameters of the Web

Service call, and can be anything you like.

6. When the Web Service is called, the service passes the values of these parameters to the parameters of the

exposed Nucleus method. There is thus a one-to-one correspondence between the parameters of the Web

Service call and the parameters of the underlying Nucleus methods.

7. The next two pages are titled EAR Name & Servlet Settings and Enterprise and Web Application Settings.

When the wizard creates a Web Service, it packages it in a WAR file, which is in turn packaged in an EAR file.

It is possible to have any number of services in a single Web application (WAR file), and any number of Web

applications in a single Enterprise application (EAR file). This flexibility gives you a good deal of control over

how you deploy your Web Services. For each new Web Service, the wizard can do any of the following:

• Create a new EAR file for the service, and put it in a WAR file within the EAR file

• Use an existing EAR file, and put the service in a new WAR file within it

1 Creating and Using Web Services 7

• Put the service in an existing WAR file within an existing EAR file

To add a Web Service to an existing EAR file, you specify that file as the EAR file name on the EAR Name &

Servlet Settings page. The Web Application Settings page then gives you the choice of creating a new Web

application for the service, or adding the service to an existing Web application.

The wizard also gives you the option of specifying the host name and port number for a Web Service, or of

leaving these fields blank. If you leave the fields blank, the values are dynamically assigned at runtime from

the URL used for the WSDL file request.

8. The Session & Security Options page allows you to specify whether the Web Service should be executed

within the context of an HTTP session. The wizard gives you these options:

• Neither provide a session nor security constraints

• Provide a session, but no security constraints

• Provide both a session and security constraints

If you want to call the Web Service from a client that uses sessions or session sharing, you must choose

one of the last two options. If you choose the last option, the wizard then prompts you to select a security

configuration. See Web Service Security (page 12) for information about security configurations for Web

Services.

9. On the Create EAR File page, click the Create EAR File button to create the Web Service. If there is already an

EAR file with the specified name, the wizard first appends .old to the name of the existing file so that new

file does not overwrite it.

Once you have created an EAR file, you must deploy it in order to run the Web Services in it. See the Deploying

Web Services (page 13) section for more information.

Naming Restrictions

Most of the class names and filenames for Web Services are generated automatically by the wizard. As a result,

certain circumstances can result in naming conflicts. For example, if you create a Web Service from a Nucleus

method, you cannot then create a second Web Service from another method with the same name (such as

an overloaded method) and put it in the same WAR file, even if the two methods have different signatures or

capitalization. If you attempt to do this, the second Web Service simply overwrites the first.

To prevent the second service from overwriting the first, put the second service in a different WAR file. In

addition, be sure to give the second WAR file a different context root from the first WAR file. (The default value

for the context root in the wizard is based on the method name, so you will need to change the value when you

run the wizard.) It is then be possible to differentiate calls to the two services based on their context roots.

Anatomy of a Web Service

As mentioned above, the Web Service Creation Wizard automatically performs a number of tasks, greatly

simplifying the creation of Web Services from Nucleus components. The wizard enables you to simply create

Web Services and begin using them, without needing to understand all of their underpinnings. However, in

some cases you may need to troubleshoot or make changes to your Web Services, so it is helpful to have some

familiarity with their form and packaging. This section discusses the various pieces that make up a Web Service,

including:

• Service endpoint interface and implementation class

8 1 Creating and Using Web Services

• WSDL document

• web.xml file

• JAX-RPC deployment descriptor (webservices.xml) and mapping file

• Runtime classes

• JSR 109 compliant EAR file

Note that the business logic of the Web Service is actually contained in the method of the Nucleus component

that is being exposed. The Web Service handles only the RPC infrastructure, and passes the actual processing to

the Nucleus component.

Service Endpoint Interface and Implementation Class

The service endpoint interface (SEI) is a Java interface class that defines the methods to be exposed as a

Web Service. This interface must extend the java.rmi.Remote interface and each method must throw

java.rmi.RemoteException. The SEI for any Web Service generated by the Oracle Commerce Platform has a

single method, corresponding to the Nucleus method being exposed.

The service implementation class (also referred to as the service bean) implements the

service endpoint interface and handles the actual servicing of incoming SOAP requests.

In addition, service implementation classes generated by the Oracle Commerce Platform

implement the interface javax.xml.rpc.server.ServiceLifecyle, and extend the

atg.webservice.ManagedComponentProperties class, which registers services with the Oracle Commerce

Platform Web Service Registry. The Web Service Registry is discussed in the Managing Web Services (page

14) section.

The service endpoint interface and implementation class are generated by the /atg/webservice/

WebServiceGenerator component. The names for these classes are based on the name of the Nucleus

method being exposed. For instance, if the Nucleus method is getOrderStatus, the service endpoint interface

is named GetOrderStatusSEI, and the implementation class is named GetOrderStatusSEIImpl.

WSDL Document

Web Services Description Language (WSDL) is an XML language for describing Web Services in a platform-

independent way. A WSDL document describes a Web Service’s methods by specifying the locations of the

resources they use and defining the methods’ inputs and outputs. (A WSDL document for a Web Service

generated by the Oracle Commerce Platform always describes one method, because each Web Service can

expose only one Nucleus method.)

There must be a separate WSDL document for each Web Service. The WSDL document is generated by the /

atg/webservice/WSDLGenerator component, which is of class atg.webservice.WSDLGeneratorImpl.

This document is used for two key purposes:

• It is used by the JAX-RPC API to generate runtime classes

• At runtime, it is used by Web Service clients to look up the semantics of the SOAP messages to send to invoke

the service

When the Web Service’s input and output values are primitive types, they are defined in the primary WSDL

document. For example:

<message name="getOrderStatusInput">

1 Creating and Using Web Services 9

<part name="in0" type="xsd:string"></message>

Each non-primitive input or output requires its own WSDL document that is imported by the primary WSDL

document. Import statements similar to the following are included in the primary WSDL document when the

Web Service is created using the Dynamo Administration UI:

<import location="atg.commerce.order.status.wsdl" namespace="http://www.atg.com/atg.commerce.order.status"/>

The location specified is relative to the primary WSDL document. Some Web Service clients are

able to interpret relative locations, but others require fully qualified URLs. To work with these clients,

when the Oracle Commerce Platform receives a request for a WSDL document, it uses the servlet class

atg.webservice.WSDLFinderServlet and the filter class atg.webservice.WSDLImportFilter to

translate the location value into a fully qualified URL:

1. At runtime, JAXRPCServlet updates the SOAP address in the WSDL document to include the domain host

name and port number.

2. When WSDLFinderServlet detects a WSDL request, WSDLImportFilter appends the domain name

and port number (from the SOAP address provided by JAXRPCServlet) and the context path (by calling

request.getContextPath() on the Dynamo request) to the location value in the import statement.

The resulting import statement looks similar to this:

<import location=

"http://myhost:7881/catalog/atg.commerce.order.status.wsdl"

namespace="http://www.atg.com/atg.commerce.order.status"/>

The WSDLFinderServlet and WSDLImportFilter classes are declared in the web.xml file for the Web

application that the Web Service is a part of, as discussed in the next section. For more information about

request handling, see the Platform Programming Guide.

web.xml File

The web.xml file is the standard deployment descriptor for the Web application that the Web Service is a part of.

It declares the filters and servlets used by the service.

With Oracle Commerce Platform, the servlet that listens for the SOAP request is

com.sun.xml.rpc.server.http.JAXRPCServlet. This servlet is part of the JAX-RPC reference

implementation, and is responsible for receiving the incoming SOAP request and determining how to dispatch

the call. For example, if you create a Web Service called getOrderStatus, the entry for it in the web.xml file

looks something like this:

<servlet> <servlet-name>getOrderStatus</servlet-name> <display-name>getOrderStatus</display-name> <servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet</servlet-class> <init-param> <param-name>configuration.file</param-name> <param-value>WEB-INF/wsconfig/getOrderStatus_Config.properties</param-value> </init-param></servlet>...<servlet-mapping>

10 1 Creating and Using Web Services

<servlet-name>getOrderStatus</servlet-name> <url-pattern>/getOrderStatus/*</url-pattern></servlet-mapping>

When a call to the getOrderStatus Web Service is sent to the Oracle Commerce Platform, the JAXRPCServlet

receives the request and dispatches it based on the information in the file that the configuration.file

parameter points to. This configuration file is included in the WAR file, and looks similar to this:

port0.wsdl.serviceName=GetOrderStatusSEIServiceport0.tie=webservices.GetOrderStatusSEI_Tiewsdl.transform=trueport0.name=getOrderStatusportcount=1wsdl.location=WEB-INF/getOrderStatus.wsdlport0.servant=webservices.GetOrderStatusSEIImplport0.wsdl.targetNamespace=http\://www.atg.com/webservicesport0.wsdl.portName=GetOrderStatusSEIPort

Note that the port0.servant property is set to the name of the service implementation class. This property

designates the class that JAXRPCServlet dispatches the SOAP request to.

Handling Imported WSDL Documents in web.xml

As discussed in the WSDL Document section, there are two resources that assist in handling WSDL requests.

These resources are declared in the web.xml file:

• WSDLImportFilter, which is a filter of class atg.webservice.WSDLImportFilter, is mapped to a parent

directory that has subdirectories holding WSDL documents

• WSDLFinder, which is a servlet of class atg.webservice.WSDLFinderServlet, should be defined and

mapped to each path that will lead to a WSDL document

For example:

<filter> <filter-name>WSDLImportFilter</filter-name> <filter-class>atg.webservice.WSDLImportFilter</filter-class></filter>...<filter-mapping> <filter-name>WSDLImportFilter</filter-name> <url-pattern>/getOrderStatus/*</url-pattern></filter-mapping>...<servlet> <servlet-name>WSDLFinder</servlet-name> <display-name>WSDLFinder</display-name> <description>Used to lookup imported wsdl files.</description> <servlet-class>atg.webservice.WSDLFinderServlet</servlet-class></servlet>...<servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.order.status.wsdl</url-pattern></servlet-mapping>

1 Creating and Using Web Services 11

<servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.security.wsdl</url-pattern></servlet-mapping><servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.wsdl</url-pattern></servlet-mapping>

Web Service Registrar in web.xml

To register Web Services with the Web Services Registry, the web.xml file declares the WebServiceRegistrar

servlet, and sets it to load on startup:

<servlet> <servlet-name>WebServiceRegistrar</servlet-name> <display-name>WebServiceRegistrar</display-name> <description>ATG WebServiceRegistrar for registering servlet web-services.</description> <servlet-class>atg.webservice.WebServiceRegistrar</servlet-class> <load-on-startup>1</load-on-startup></servlet>

For more information about the Web Services Registry, see Managing Web Services (page 14).

Other Elements of web.xml

The web.xml file may declare certain additional elements:

• The servlet atg.nucleus.servlet.NucleusServlet, which runs Nucleus as a servlet within a Web

application

• The filter atg.filter.dspjsp.PageFilter, which invokes the DAF request-handling pipeline

• The context parameter atg.session.parentContextName; its value is set to /dyn, which enables the Web

Services to share information with the atg_bootstrap.war application

JAX-RPC Deployment Descriptor and Mapping Files

The JAX-RPC deployment descriptor, webservices.xml, provides metadata (such as names and descriptions of

the SEIs, service beans, and WSDL documents) about all of the Web Services in a given Web application.

The mapping file defines the association between a WSDL file and an ISEI and implementation class, by mapping

namespaces to Java packages. This mapping is used when serializing and deserializing XML files. There is a

separate JAX-RPC mapping file for each Web Service, and the name of each file reflects the method the service

is based on. For example, if the method is getOrderStatus, the mapping file for the Web Services is named

getOrderStatusMapping.xml.

Runtime Classes

The runtime classes are generated using the Oracle JAX-RPC reference implementation. These classes include:

• The tie class that JAXRPCServlet invokes the method on, and which in turn invokes the method on the

service implementation class

12 1 Creating and Using Web Services

• Classes for handling serializing and deserializing SOAP requests and responses

JSR 109 Compliant EAR File

The JSR 109 Java specification includes information about how a Web Service should be packaged within an EAR

file. The wizard combines all the generated files (class files, web.xml, WSDL document, webservices.xml, and

JAX-RPC mapping file) into a WAR file, which is then added to a JSR 109 compliant EAR file.

Web Service Security

When you create a Web Service, you have the option of applying security constraints so that only approved

clients (those with administrator privileges, for example) can execute it. You specify the security constraints

using a security configuration, which is a repository item that stores information that controls access to the Web

Service. You can create any number of different security configurations using the Web Services Administration

UI, and you can apply a security configuration to any number of Web Services.

A security configuration has a corresponding security policy component, plus an optional ACL. A security

configuration is identified by its functional name, which is a property of the repository item that maps the

security configuration to a security component and ACL.

This section describes the main components involved in securing Web Service methods, as well as how to create

security configurations through the Web Services Administration UI. For a broader discussion of the Oracle

Commerce Platform security API, see the Managing Access Control section in the Platform Programming Guide.

Security Components

There are two primary components involved in securing a Web Service method:

• /atg/webservice/security/NucleusSecurityManager (an instance of

atg.webservice.NucleusSecurityManager) uses the security configuration associated with the Web

Service to apply the corresponding security policy and ACL, to determine whether to grant or deny access.

See NucleusSecurityManager (page 12)

• /atg/webservice/security/NucleusSecurityRepository (an instance of

atg.adapter.gsa.GSARepository) stores the Web Service security configurations used by the

NucleusSecurityManager. See NucleusSecurityRepository (page 13)

NucleusSecurityManager

At startup time, the NucleusSecurityManager retrieves the repository items from the

NucleusSecurityRepository (described below) and creates an internal mapping between each functional

name and the SecurityPolicy component and ACL associated with it.

When a client calls a Web Service, the service invokes the hasAccess() method on the /atg/webservice/

security/NucleusSecurityManager component, passing it the functional name of the service’s security

configuration, the name of the Nucleus component and method exposed by the service, and a Map containing

the method’s parameters. The NucleusSecurityManager uses the functional name to find the associated

SecurityPolicy component and ACL, applies them to the call, and returns the result (true or false) to the

client. If true is returned, the Nucleus method exposed by the Web Service is invoked; if false is returned,

access to the method is denied, and an exception of class atg.security.SecurityException is thrown.

If the NucleusSecurityManager is unable to apply the security configuration to a Web Service call (for

example, if the SecurityPolicy is not valid), it determines whether to grant access based on the value of its

defaultGrantAccess property. The default value of this property is false (deny access).

1 Creating and Using Web Services 13

Setting defaultGrantAccess to true facilitates the development process, because it allows any Web Service

that does not have an associated security configuration to be called by any client.

For deployment purposes, though, this behavior is undesirable, because of the security risks involved. Therefore,

when you enable liveconfig settings for the Oracle Commerce Platform, the defaultGrantAccess property

is set to false. Note, however, that this means that each of your Web Services must have an associated security

configuration, because any call to a service without a security configuration will fail.

For information about enabling liveconfig settings, see the Platform Installation and Configuration Guide

NucleusSecurityRepository

Web Service security configurations are stored in the NucleusSecurityRepository. This repository includes

a single item descriptor called nucleusSecurity, which has properties called functionalName, policy, and

ACL. The NucleusSecurityManager parses the items in this repository at startup time.

The Web Services Administration interface provides an easy way to add new security configurations to this

repository. See the next section for details.

Creating and Editing Security Configurations

The Web Services Administration page in the Dynamo Server Admin includes a Web Service Security Manager

link that takes you to a page that where you can view and edit the security configurations stored in the

NucleusSecurityRepository, or create new security configurations.

Follow these steps to create a new security configuration:

1. Click the Create New link.

2. On the Create Security Configuration page, enter a name for the security configuration in the Functional

Name field, and click Create New button.

3. On the Edit Web Service Security Configuration page, click the Add buttons to add users, roles, and

organizations to the security configuration. You can change the security policy (from the /atg/dynamo/

security/SecurityPolicy default) if necessary.

The new security configuration appears on the main Web Service Security Configurations page. If you need to

make changes to it, click the Edit link to open the Edit Web Service Security Configuration page. Note that you

cannot change the functional name.

Deploying Web Services

When you create a Web Service, the wizard places the EAR file in the <ATG11dir>/home directory. The Web

Service is not ready to run, however, because it does not include the necessary Nucleus classes.

In order to run the Web Service, these additional steps are necessary:

1. Use the runAssembler command to assemble a Nucleus-based application, using the

-add-ear-file flag to incorporate the contents of the Web Services EAR file.

2. Deploy the assembled EAR file on your application server, and start up the application.

For example, if your Web Services EAR file is called WS.ear, you might use a command like this to assemble a

Nucleus-based application named MyApp.ear:

14 1 Creating and Using Web Services

runAssembler -add-ear-file WS.ear MyApp.ear -m MyApp DSS

If you make any subsequent changes to the Web Service, you must reassemble and redeploy the application for

the changes to take effect.

Note that in addition to any Web Services you create, the Oracle Commerce Platform includes a number of

prepackaged Web Services. These services are packaged in three separate application modules. You can include

any of these services in an assembled EAR file by including the module that contains the desired services. For

example, to include the prepackaged Core Commerce Web Services, specify the DCS.WebServices module

when you assemble your application.

For more information about the runAssembler command, see the Platform Programming Guide. For information

about deploying EAR files, see the documentation from your application server vendor.

Managing Web Services

The Dynamo Server Admin UI provides a facility for managing the Web Services deployed on your server.

To access this facility, open the top-level page of the Dynamo Server Admin UI and click the Web Service

Administration link. On the Web Service Administration page, click the Web Service Registry link. This takes you

to the page for the /atg/webservice/WebServiceRegistry component, which stores information about the

available Web Services.

For example, if the Web Services included with Oracle Commerce Platform are running on your Dynamo server,

the top of the page will look similar to this:

The Service Info indicates that there are six Web applications running that include Web Services. You can get

more information about the services in a Web application by clicking the Details link next to the application’s

name. For example, if you click on the link for the Pricing application, the Service Info looks like this:

1 Creating and Using Web Services 15

The lower table summarizes the status of the Web Services in the Web application. The Name and URI

Pattern are the values of the display-name and url-pattern tags in the web.xml file, and the WSDL file

is the value of the wsdl.location property in the configuration file for the JAXRPCServlet. The Security

functional name is the name that the service implementation class passes to the hasAccess() method of the

NucleusSecurityManager to determine if the client has permission to call the Web Service.

Some of the information shown in this table, such as the functional name, does not appear until the Web Service

has been executed. If a service has been executed, the Instance Running and Registered value is true. You can

stop a running service by clicking the Off link in the Enabled column.

Registering Services

Web Services generated by the Web Service Creation Wizard have the necessary code and configuration

information to register the Web Service with the Web Service Registry.

To register the service, the service implementation class extends the class

atg.webservice.ManagedComponentProperties, which includes a register() method for registering

the service. In addition, the web.xml file for the Web application the service is part of declares the

WebServiceRegistrar servlet, as described in the Anatomy of a Web Service (page 7) section.

Creating JMS Web Services

In addition to Web Services that call Nucleus methods, the Oracle Commerce Platform enables you to create

Web Services that send JMS messages through Patch Bay. Many events in the Oracle Commerce Platform

16 1 Creating and Using Web Services

are triggered by JMS messages, so by calling a Web Service that sends a JMS message, a client can start

execution of various services and processes. In particular, scenario actions are triggered by JMS messages, so

you can use Web Service calls to invoke scenario actions remotely. For example, suppose a new user registers

in some application, which invokes a Web Service that sends the registration information to the Oracle

Commerce Platform. The client application could then call a Web Service that sends a JMS message of type

atg.dps.Register into Patch Bay, thereby triggering a scenario action that (for instance) sends an e-mail

message to the new user.

This section discusses how to create Web Services that send JMS messages, and how to configure components

to listen for these messages. For more information about JMS and Patch Bay, see the Dynamo Message System

chapter of the Platform Programming Guide.

Using the JMS Message Web Service Wizard

To create a Web Service that sends a JMS message, you use the Web Service Creation Wizard, just as you do

for Web Services that invoke Nucleus methods. On the first screen of the wizard, however, you click the JMS

Message Web Service link (rather than the Component Method Web Service link). In this version of the wizard,

you do not select a Nucleus component and method; instead, the key selections are the message type and

the Patch Bay port name to use. The message type is the JMSType value for the message. This is a String,

stored in the message’s header, that identifies the kind of message it is. For example, a message of JMSType

atg.dps.PageVisit is sent when a site visitor displays a page.

For the port name, the wizard gives you two options, IndividualEvents and GlobalEvents. These are the

standard ports where the Scenario Manager listens for scenario events.

The names of the classes generated by the wizard are based on the JMS message type of the message. For

example, if you create a Web Service that sends a message whose JMSType is atg.dps.PageVisit, the service

implementation interface is named SendPageVisitSEI, and the service implementation class is named

SendPageVisitSEIImpl.

Structure of a JMS Web Service

JMS Web Services generated by the wizard are similar to Web Services that call Nucleus methods. JMS services

expose a Nucleus method, but it is always the receiveObjectMessage() method of the component /atg/

dynamo/messaging/MessageImporter. This method receives the message object and forwards it into Patch

Bay.

The receiveObjectMessage() method takes three parameters:

• The message object

• A String indicating the JMSType of the message

• A String indicating the Patch Bay port name to use

The Web Service call itself takes only a single argument, the message object. The JMSType and port name are

hard-coded when you generate the Web Service, and the service implementation class passes them (along

with the message object supplied by the client) to the receiveObjectMessage() method. This simplifies the

client’s task, because it does not need to be aware of either the JMSType or the port name.

For example, a Web Service that sends a JMS message when a user views a page would be called like this:

public void sendPageVisit(atg.userprofiling.dms.PageVisitMessage a);

1 Creating and Using Web Services 17

The service implementation class then calls the receiveObjectMessage() method like this:

messageImporter.receiveObjectMessage(a, "atg.dps.PageVisit", "IndividualEvents");

For information about calling Web Services that send JMS messages from Java clients, see the Accessing Web

Services from Java Clients (page 35) section. (Note that you cannot use the dynamic process described in

that section for calling these Web Services.) For information about calling Web Services that send JMS messages

from .NET clients, see the Accessing Web Services from .NET Clients (page 44) section.

Patch Bay Configuration

The /atg/dynamo/messaging/MessageImporter component, whose receiveObjectMessage() method

is invoked by JMS Web Services, is a Patch Bay message source. When a Web Service invokes the method, the

message passed to that method is sent either to the destination patchbay:/sqldms/MessageImporter/

IndividualEvents or to patchbay:/sqldms/MessageImporter/CollectiveEvents, depending on the

message type.

The standard Patch Bay configuration file, /atg/dynamo/messaging/dynamoMessagingSystem.xml,

includes the necessary declarations for the message source and destinations:

<message-source> <nucleus-name> /atg/dynamo/messaging/MessageImporter </nucleus-name>

<output-port> <port-name> IndividualEvents </port-name> <output-destination> <destination-name> patchbay:/sqldms/MessageImporter/IndividualEvents </destination-name> <destination-type> Topic </destination-type> </output-destination> </output-port> <output-port> <port-name> GlobalEvents </port-name> <output-destination> <destination-name> patchbay:/sqldms/MessageImporter/CollectiveEvents </destination-name> <destination-type> Queue </destination-type> </output-destination> </output-port></message-source>

18 1 Creating and Using Web Services

The Scenario Manager is a message sink configured to receive messages from these destinations. This

configuration occurs in two places:

• In the standard Patch Bay configuration file, the Scenario Manager is configured to receive individual scenario

events from the destination patchbay:/sqldms/MessageImporter/IndividualEvents

• In the /atg/dynamo/messaging/dynamoMessagingSystemDSSGlobal.xml file, the Scenario Manager is

configured to receive global scenario events from the destination patchbay:/sqldms/MessageImporter/

CollectiveEvents

You can configure other message sinks to receive messages from the patchbay:/sqldms/MessageImporter/

IndividualEvents destination by declaring them in the dynamoMessagingSystem.xml file. Note, however,

that you cannot configure other sinks to receive messages from patchbay:/sqldms/MessageImporter/

CollectiveEvents. This destination is a queue, used by global Scenario Managers only; adding sinks to this

destination may interfere with the global Scenario Managers receiving messages. If you want another message

sink to receive these messages, configure an additional destination for MessageImporter to send global

scenario events to, and configure your sink to listen to that destination instead.

Creating Repository Web Services

The Dynamo Serve Admin interface provides an easy, browser-based way to create Web Services based on

repository items. This Repository Web Service wizard is part of the Web Service Administration user interface,

which is introduced in the Web Service Creation Wizard (page 5) section of the Creating Custom Web

Services (page 4) section. You can use the Repository Web Service wizard to create Web Services that add,

remove, update, or get a complete repository item, or a single property of a repository item.

Using the Repository Web Service Wizard

To use the Repository Web Service wizard to create a repository Web Service:

1. Open the Dynamo Server Admin interface and navigate to the Web Service Administration > Web Service

Creation Wizard > Repository Web Service page.

2. Identify the repository component that the Web Service should access. You can do this in one of two ways.

The Create Repository Web Service page displays a text field in which you can enter the Nucleus address of

the repository component and click the Submit button. The Create Repository Web Service page also displays

a list of all repository components that are registered in the initialRepositories property of the /atg/

registry/ContentRepositories component. You can select a repository component by clicking the link

with the Nucleus address of the repository component.

3. The next page, with the heading Select item descriptor, displays all of the item descriptors in the repository

component you selected. Click the link for the item descriptor you want to expose in your Web Service.

4. The next page, with the heading Select Method, displays the methods that are available for the item

descriptor you selected. For example, if the item descriptor is mutable, the following methods are available:

• add

• remove

• update

1 Creating and Using Web Services 19

• get

The Select Method page also allows you to create a Web Service for a specific property. The page displays a

list of links for each of the properties of the item descriptor you selected. Click one of these property names to

create a Web Service for an individual repository item property.

The property name link leads to a list of the Web Service methods that are available for that repository item

property, as well as notes about the Web Service limitations, if any, related to the repository item property.

See Repository Web Service Limitations (page 19) for more information.

Click the name of the method you want to expose in your Web Service.

5. In the EAR Name & Servlet Settings page, the Web Service Creation Wizard displays default names for the

EAR file and servlet to be created. You can modify the default names. You can also, if you choose, enter a

description for the servlet and a network hostname and port number for the Web Service. If you leave the

fields blank, the values are dynamically assigned at runtime from the URL used for the WSDL file request. You

should generally leave these fields blank, unless you want to require the Web Service to be accessed on a

specific server and port.

Enter any settings you want to change and click the Next button.

6. In the Enterprise & Web Application Settings page, the Web Service Creation Wizard displays default names

for the enterprise application and Web application to be created. You can modify the default names. You can

also, if you choose, enter a description for the enterprise application and Web application.

Enter any settings you want to change and click the Next button.

7. The Session & Security Options page allows you to select one of the following three options for the Web

Service:

• Provide neither a session nor security constraints

• Provide a session, but no security constraints

• Provide both a session and security constraints

If you choose the last option, the wizard then prompts you to select a security configuration. See the Creating

Custom Web Services (page 4) section for information about security configurations for Web Services.

8. The Create EAR File page displays the parameter values you have selected for your Web Service. Review them,

then click the Create EAR File button to create the Web Service.

The Web Service is created in an EAR file. You will find the EAR file in the <ATG11dir>/home directory, with

the name you selected in step 4.

To use the new Web Service, you need to deploy it. See the Deploying Web Services (page 13) section.

Repository Web Service Limitations

Because of the limitations inherent in Web Services, repository items must generally be passed in XML form.

See the Repository to XML Data Binding (page 21) section for information about transforming repository

items into XML files and vice versa. In particular, you should bear in mind the following restrictions when you are

creating repository Web Services:

get/setPropertyValue

• Collection properties may not be set or gotten as a whole. Only elements of the collection may be set

20 1 Creating and Using Web Services

• RepositoryItem properties are set or gotten as Strings in XML form

• There is no type of service that can get or set sub-properties. You must act upon the actual RepositoryItem

you wish to read from or write to

• You cannot get or remove elements from a set or list. This is because in order to remove elements from either,

you need to provide the object to remove (or index, see below), and a Web Service cannot guarantee that that

object is of a type that can be transformed from XML into a Java object

• You cannot get or set a property of a type that corresponds to a Java primitive. For example, you cannot get or

set a java.lang.Integer or a java.lang.Boolean

• You cannot get or set a property of a non-simple type, other than atg.repository.RepositoryItem. This

includes types such as java.util.Timestamp and java.sql.Date. Note, however, that if you retrieve a

Date property, a java.util.Calendar will be returned

• You cannot get a property that is not readable, or set a property that is not writable

addItem

• The item to be added must be supplied in XML form

updateItem

• The item to be updated must be supplied in XML form

• By default, when a repository item is passed into the Web Service, the existing RepositoryItem is found by

matching repository IDs. We determine the value of the repository ID from the top-level XML element in the

instance document, and then find a repository item with a matching ID

removeItem

• Users must pass in only the repository ID of the item to be removed

Modifying Repository Web Services

Note that when you create a repository Web Service using the Web Service Creation Wizard, the component

path of the repository, the item descriptor name and, if applicable, the property name, are all hardcoded in the

generated Web Service. If any of these variables is changed, the Web Service will need to be regenerated.

Please note that the repository name is not taken into consideration when naming the Web Service. Only the

item descriptor name and, if applicable, property name, is used to name a service. This means that if you are

generating Web Services for two or more repositories with the same item descriptor names, you should consider

placing them into different WAR files, or giving them different servlet URLs.

RepositoryService Class

The atg.repository.RepositoryService class contains many methods that perform basic Repository

operations, independent of any particular repository implementation or instance. Such operations include

getting, adding, removing and updating a repository item, setting and getting properties of repository items,

and performing queries for repository items using RQL. Using the Web Service generator, you can directly make

some of these methods into Web Services by simply clicking a form submit button.

Some others of these methods are too generic to be made available as a Web Service without limiting the

types of the inputs or outputs. For example, the method setPropertyValue takes a java.lang.Object as a

1 Creating and Using Web Services 21

method argument for the property value. Since Web Services does not allow java.lang.Object as an input

(or output), this method cannot be used as a Web Service in this form. However, we can restrict the type of this

argument using the code generator template functionality, so when the Web Service is generated, the outward-

facing method will be strongly typed based on the property being set, and can simply call through to the more

generic setPropertyValue method in the body of the Web Service. The RepositoryService class has the

following properties:

Property Name Type Description

transaction

Manager

javax.transaction.

TransactionManager

The service that manages any transactions that are

used to execute repository methods on this instance.

mappingManager atg.repository.xml.

ItemDescriptor

MappingManager

The component that manages mapping files

based on repository and item descriptor name

combinations. For any methods that return a

RepositoryItem, this service will be consulted to

retrieve mapping files to use when transforming

these items into XML. See the Mapping Files

and XML Schemas (page 22) section for

more information abut mapping files and the

ItemDescriptorMappingManager class.

xmlGetService atg.repository.xml.

GetService

The service that knows how to turn

RepositoryItems into XML.

xmlAddService atg.repository.xml.

AddService

The service that knows how to add

RepositoryItems in XML format to a repository.

xmlUpdateService atg.repository.xml.

UpdateService

The service that knows how to take

RepositoryItems in XML format and update them

in their corresponding repositories.

For information about the XML service properties, see the Repository Operations (page 29) section.

Repository to XML Data Binding

One of the key aspects of integrating the Oracle Commerce Platform with a remote system is sharing data

between the two systems. Data sharing and synchronization are often complex, because the two systems

may store their data in dissimilar formats. The Oracle Commerce Platform data is typically stored in a Dynamo

repository, which handles the mapping of data in Java objects to the underlying data store (such as a SQL

database).

The Oracle Commerce Platform Integration Framework includes a data binding facility for reading and writing

data between a repository and XML documents. Using this facility, you can write out repository data to XML

documents that can then be read into a remote system, or read data into a repository from XML documents that

store data from a remote system. A key aspect of this system is the use of mapping files to specify the data to

include or exclude, and to map the names of repository properties to the names used by the remote system.

22 1 Creating and Using Web Services

The data binding facility also includes tools for generating XML Schemas that describe the structure of data in a

repository, and to use these XML Schemas to validate the data written out from or read into the repository. For

information on the Integration Framework, refer to the Platform Programming Guide.

The data binding facility provides services that perform these four operations with repository items:

• Getting items (retrieving items from a repository and writing them out to XML documents)

• Adding items (creating new items in a repository from data in XML documents)

• Updating items (modifying existing items using data in XML documents)

• Removing items (deleting items as indicated in XML documents)

This section discusses:

Mapping Files and XML Schemas (page 22)

Repository Operations (page 29)

Note that the classes described in this section work only with repositories included in the

initialRepositories property of the /atg/registry/ContentRepositories component.

Mapping Files and XML Schemas

In addition to the XML instance documents that store the actual data, data binding uses two other types of

documents:

• Mapping files control which data is exchanged between system, and which data is omitted

• XML Schemas describe the structure of the data, and can be used to validate XML instance documents

Mapping Files

When you exchange data between the Oracle Commerce Platform and a remote system, you will typically want

to exclude certain data. For example, the Core Commerce profile usually includes Dynamo-specific information

about scenarios.

When you create an XML instance document from data in a repository, Dynamo includes and excludes certain

properties by default:

• If a property is readable and does not point to another item descriptor, it is included

• If a property is readable, points to another item descriptor, and its cascade attribute is set to "delete", it is

included

• All other properties are excluded

For more information about the default inclusion rules, see the isIncludeProperty() method of the

atg.repository.xml.RepositoryXMLTools class in the ATG Platform API Reference. RepositoryXMLTools

is a utilities class with various methods for encoding and decoding item descriptors, property names, and

mapping files to and from XML-compatible namespaces and identifiers.

If you want more explicit control over the properties that are written out, you can use a mapping file. A mapping

file specifies what properties to include or exclude when moving data between a repository and an XML

instance document, and provides a way to map the names of Dynamo properties to their equivalents in a

remote system. For example, a Dynamo profile might have an email property that stores the same information

as the Email_Address attribute on another system.

1 Creating and Using Web Services 23

The following is the Document Type Definition (DTD) for mapping files:

<!--This is the XML DTD for ItemDescriptorMapping-->

<!--

Specifies what properties in an item-descriptor should be included inanother datamodel. A given mapping file gives the ability tocontrol what properties are included/excluded from the datamodelcontrol how names in one model relate to names in another model

-->

<!--Defines the mapping for a given item-descriptor. The name and repositoryproperty are required properties. The name property corresponds to thename of a given item-descriptor. The repository should be the Nucleuspath to a particular repository. For example, if an item-descriptor mappingwas going to point to the the ProfileAdapterRepository located at/atg/userprofiling/ProfileAdapterRepository Nucleus path, then the repositoryproperty should be the string "/atg/userprofiling/ProfileAdapterRepository".The default-include exists to indicate whether or not properties that areassociated with this item-descriptor should be included by default or not.This property defaults to true. So, if a property is does not explicitlyappear as a child property element, it is assumed to be included in thedata model to be exported.--><!ELEMENT item-descriptor (property*)>

<!ATTLIST item-descriptor repository-path CDATA #IMPLIED name CDATA #IMPLIED default-include (true | false) #IMPLIED>

<!--A property element controls two aspects of including a property in a givenmapping; whether the property should be included or not and what thetargetName for the target datamodel should be. The name attribute correspondsto the name of a property defined for a given item-descriptor. The includeattribute is optional. If it is not specified, the value is obtained from thedefault-include value of the enclosing item-descriptor.--><!ELEMENT property (item-descriptor*)>

<!ATTLIST property name CDATA #REQUIRED include (true | false) #IMPLIED targetName CDATA #IMPLIED>

The following is a sample mapping file for the Dynamo profile repository:

<!DOCTYPE item-descriptor SYSTEM "http://www.atg.com/dtds/databinding/itemDescriptorMapping_1.0.dtd"><item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository"

24 1 Creating and Using Web Services

name="user" default-include="true"> <property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property> <property name="slotInstances" include="false"/> <property name="scenarioInstances" include="false"/> <property name="mailings" include="false"/> <property name="scenarioValues" include="false"/> <property name="firstName" targetName="first_name"/></item-descriptor>

The data binding services all work with a single item descriptor and its properties (including any other item

descriptors that are properties of the main item descriptor). The mapping file uses the item-descriptor tag to

specify the repository and item descriptor that the mapping file is associated with:

<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true">

The default-include attribute specifies whether the item’s properties should be included or excluded by

default. This value can be overridden for individual properties. In this mapping file, various scenario-related

properties are excluded:

<property name="slotInstances" include="false"/><property name="scenarioInstances" include="false"/><property name="mailings" include="false"/><property name="scenarioValues" include="false"/>

If a property is an item descriptor, there must be an item-descriptor tag inside the property tag. For

example, the homeAddress property points to a contactInfo item descriptor:

<property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property>

Note that the item-descriptor tag for contactInfo can have property tags within it. The nesting of

property tags and item-descriptor tags must reflect the hierarchy of the item descriptors in the repository.

If you do not include a property tag for a property that points to an item descriptor (such as the homeAddress

property shown above), the Oracle Commerce Platform uses the default inclusion rules for determining which

properties of that item descriptor to include.

Finally, the property tag has an optional targetName attribute for mapping the property name to its

corresponding name in the remote system:

1 Creating and Using Web Services 25

<property name="firstName" targetName="first_name"/>

Managing Mapping Files for Repository Item Descriptors

The Oracle Commerce Platform includes two classes that help identify the appropriate mapping file for each

item descriptor that you want to use with the repository2xml data binding facility. These classes are used by

Web Service clients:

atg.repository.xml.ItemDescriptorMappingatg.repository.xml.ItemDescriptorMappingManager

ItemDescriptorMapping

An ItemDescriptorMapping is a simple bean that holds information about relationships between repository

item descriptors and mapping files. The mapping files describe what properties are to be exposed when

an item from that item descriptor is to be transformed into XML. Each ItemDescriptorMapping pertains

to exactly one repository: for example, you would have a UserProfileItemDescriptorMapping, or a

PromotionItemDescriptorMapping component, each of which would provide a list of item descriptor names

from the corresponding repository and their corresponding mapping files.

An ItemDescriptorMapping contains only three properties:

Property Name Type Description

repositoryPath java.lang.String The path to the repository supported by this

ItemDescriptorMapping. This is a read-only

property

repository atg.repository.

Repository

The path to the repository supported by

this ItemDescriptorMapping. Similar to

repositoryPath but this property will

resolve to an actual Repository instance, and

is writeable.

itemDescriptorMapping java.util.Map A map where the keys are item descriptor

names and the values are locations of

mapping files, relative to the configuration

path, which provide rules for how an item of

the keyed item descriptor name appears in

XML format

Here is an example properties file for an ItemDescriptorMapping that supports the profile repository:

$class=atg.repository.xml.ItemDescriptorMappingrepository=/atg/userprofiling/ProfileAdapterRepositoryitemDescriptorMapping=\ user=/atg/userprofiling/userMapping.xml,\ contactInfo=/atg/userprofiling/contactInfoMapping.xml

26 1 Creating and Using Web Services

Here we see the there are two entries in the itemDescriptorMapping property, one for the user item

descriptor, and one for the contactInfo item descriptor.

Whenever an entry is added to the itemDescriptorMapping property, whether through a properties file,

or directly in code, the ItemDescriptorMapping checks to make sure that the key of the entry, the item

descriptor name, resolves to an actual item descriptor of the repository this service is configured to support. If

any item descriptor name does not resolve, a RepositoryException is thrown.

By themselves, ItemDescriptorMappings perform no work. They simply hold state. In order to put them to

work, you must add them to the ItemDescriptorMappingManager, described below.

ItemDescriptorMappingManager

Class atg.repository.xml.ItemDescriptorMappingManager

Component /atg/repository/xml/ItemDescriptorMappingManager

Module DAS

The ItemDescriptorMappingManager serves as a registry of ItemDescriptorMappings. It is through this

service that you obtain mapping files for all repository and item descriptor combinations. The mapping files are

registered in the itemDescriptorMappings property of the ItemDescriptorMappingManager component:

Property Name Type Description

itemDescriptorMappings atg.repository.xml.

ItemDescriptor

Mapping[]

An array of ItemDescriptorMapping

components. When a user calls methods to

retrieve mapping files, this component sifts

through the itemDescriptorMappings to

determine the correct mapping.

Here is an example properties file:

$class=atg.repository.xml.ItemDescriptorMappingManageritemDescriptorMappings=\ /atg/userprofiling/UserProfileItemMapping,\ /atg/userprofiling/ContactInfoItemMapping

The following ItemDescriptorMappingManager methods can be used to retrieve mapping files:

getMappingFileName(String pRepositoryPath, String pItemDescriptorName)

Using the given repository path and item descriptor name, returns the mapping file for that given path:name

combination, or null if none exists.

getMappingFileName(Repository pRepository, String pItemDescriptorName)

Using the given repository and item descriptor name, returns the mapping file for that given repository:name

combination, or null if none exists.

1 Creating and Using Web Services 27

When you use the atg.repository.xml.GetService to get repository items in XML form, you can

pass along a mapping file name using these ItemDescriptorMappingManager methods. Using the

ItemDescriptorMappingManager, you can centralize all mapping files in one component for all item

descriptors, and just call that to determine which mapping file to use for a given item descriptor.

XML Schemas

The Oracle Commerce Platform provides tools for creating and working with XML Schemas for the XML

documents written and read by the various data binding services. XML Schema is a schema language for XML

that describes and restricts what a particular XML instance document might look like. An XML document can be

validated against an XML Schema to check that it conforms to that Schema. Additionally, many developer tools

make use of XML Schemas. For example, some tools provide a visual representation of XML Schemas to allow

mapping from one XML Schema to another. See Generating XML Schemas (page 27).

Generating XML Schemas

The Oracle Commerce Platform provides a command-line tool that generates an XML Schema for a given item

descriptor. The XML generated by the Get data binding service conforms to this Schema. Similarly, the XML

Schema describes an instance document that is capable of being processed by the Add, Update, or Remove

service.

The command-line tool is named generateXMLSchema.sh (on Unix) or generateXMLSchema.bat (on

Windows) and is found in the <ATG11dir>/home/bin directory. The following table lists the arguments that

can be supplied to this command:

Argument Description

-repository Nucleus path to the repository containing the item descriptor that the XML

Schema is being generated for. Required.

-itemDescriptor Name of the item-descriptor that the XML Schema is being generated for.

Required.

-outputDirectory Specifies a directory to save the XML Schema to. This directory is in addition

to the directory specified by the XMLSchemaFileDirectory property of the

XMLSchemaManager. Not required.

-saveSchemas If set to true, then the Schemas will be saved via the configured

XMLSchemaManager. If omitted, defaults to true.

-mappingFile Specifies the mapping file to use. Not required.

-schemaGenerator Nucleus path to the Schema Generator component. If omitted, defaults to /

atg/repository/xml/SchemaGenerator.

-m Specifies the set of modules to use in the repository definition. Required.

-help Prints out a usage message. Not required.

The following command generates an XML Schema for the user item descriptor of the default Dynamo profile

repository, using the properties defined in the repository definition file for the DSSJ2EEDemo application

module (and the modules required by the DSSJ2EEDemo module):

28 1 Creating and Using Web Services

generateXMLSchema -m DSSJ2EEDemo –repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user

The generated XML Schema is saved by the Schema Manager specified by the schemaManager property

of the Schema Generator component. The default Schema Generator is the /atg/repository/xml/

SchemaGenerator component, and its schemaManager property points by default to the /atg/repository/

xml/SchemaManager component. Note that if the user item descriptor contains other item descriptors as

properties, the generated Schema will reflect these other item descriptors as well.

To save the Schema to the current working directory in addition to the directory determined by the

XMLSchemaFileDirectory property of the Schema Manager:

generateXMLSchema -m DSSJ2EEDemo –repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -outputDirectory .

Managing Schemas and Mapping Files

As mentioned above, the default Schema Generator has a schemaManager property that points to the

/atg/repository/xml/SchemaManager component. In addition, each of the data binding service

components (described below) has an XMLSchemaManager property that points to this SchemaManager

component. This component is of class atg.repository.xml.XMLSchemaManager. This class, which extends

atg.repository.databinding.MappingManager, manages XML Schemas and mapping files. For example,

this class has mappingFileDirectories and XMLSchemaFileDirectory properties that specify the

directories where mapping files and Schemas are stored. Note that Schemas must have the extension .xsd and

mapping files must have the extension .xml.

For example, suppose you want to generate an XML Schema and specify a mapping file to use. The command

would look something like this:

generateXMLSchema -m DSSJ2EEDemo –repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -mappingFile profileMapping.xml

Notice that only the name of the mapping file is specified, not the entire pathname. The Schema Manager’s

mappingFileDirectories property points to the directories where the mapping file should be stored.

PropertyElementNameSeparator

The repository2xml feature specifies a separator character, which functions to separate a property name

from the name of its item descriptor. By default, this separator character is . (dot). The default separator

character may not work for you if, for example, you use composite repository IDs that also use the . (dot)

character to separate elements of the repository ID. You can specify a different separator character in the

propertyElementNameSeparator property of the /atg/repository/xml/RepositoryXMLTools

component.

Item References

In a repository schema, a map, set, list, or array property can point to a single other item using the itemRef

attribute. The value assigned to the itemRef attribute concatenates the item descriptor name, the property

element separator, and the repository ID. In the following example, the item descriptor name is role, the

property element separator is . (dot) and the repository ID is 2900004:

1 Creating and Using Web Services 29

<user:itemRef itemRef="role.2900004"/>

The following is a more extended example, showing the context for the itemRef attribute:

<user:user xmlns:user=http://www.atg.com/ns/profileMapping/UserProfiles/user xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd " ID="user747"> <user:homeAddress itemRef="contactInfo.1040001"/> <user:roles> <user:itemRef itemRef="role.2900004"/> <user:itemRef itemRef="role.3000008"/> </user:roles></user:user>

Repository Operations

The atg.repository.xml package includes a service class for each of the four repository operations

supported by the data binding facility. The following table lists these classes and the Nucleus instances included

in Dynamo:

Class Nucleus component

atg.repository.xml.GetService /atg/repository/xml/GetService

atg.repository.xml.AddService /atg/repository/xml/AddService

atg.repository.xml.UpdateService /atg/repository/xml/UpdateService

atg.repository.xml.RemoveService /atg/repository/xml/RemoveService

The following sections discuss each of these classes and the operations they perform. See the entries for these

classes in the ATG Platform API Reference for more information.

Getting Repository Items

You use getItemAsXML() method of the atg.repository.xml.GetService class to create XML documents

from repository items. This method takes a repository item as an input argument and returns a String

containing an XML representation of this item. If you write out this String (e.g., to a file), be sure to use the

same character encoding that the repository uses.

Some versions of the getItemAsXML() method take additional inputs for specifying a String array of the

names of the properties to write out or a String containing the name of the mapping file to use. If you

supply only a repository item as input, the method uses the default inclusion rules (described in the Mapping

Files (page 22) section) to determine which properties to include.

By default, GetService writes out an XML document as a single line, because it is intended to be machine-

readable. If you want the generated XML to be human-readable, set the indentXMLOutput property of the

GetService component to true. The resulting XML will have appropriate line breaks.

30 1 Creating and Using Web Services

The following example shows a repository operation to get a repository item.

Suppose you want to generate XML for a user profile, based on a mapping file named profileMapping.xml.

The following code finds the user repository item whose ID is "user747" and generates an XML representation

of it:

RepositoryItem userItem = getProfileRepository().getItem("user747", "user");String userAsXML = GetService.getItemAsXML(userItem,"profileMapping.xml");

The following is sample output from this code. The data represents the profile of the user sandy in the following

demo:

<user:user xmlns:user="http://www.atg.com/ns/profileMapping/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd " ID="user747"> <user:securityStatus>0</user:securityStatus> <user:actualGoals>long-term</user:actualGoals> <user:gender>female</user:gender> <user:fundShares> <user:integer>500</user:integer> <user:integer>220</user:integer> <user:integer>180</user:integer> <user:integer>260</user:integer> </user:fundShares> <user:goals>short-term</user:goals> <user:dateOfBirth>1976-12-09</user:dateOfBirth> <user:pubPrivileges>none</user:pubPrivileges> <user:homeAddress> <user:homeAddresscontactInfo ID="contactInfo747"/> </user:homeAddress> <user:numberNewsItems>4</user:numberNewsItems> <user:strategy>conservative</user:strategy> <user:locale>en_US</user:locale> <user:lastActivity>2002-08-14T18:33:49.604</user:lastActivity> <user:aggressiveIndex>5</user:aggressiveIndex> <user:lastName>Pieta</user:lastName> <user:actualStrategy>conservative</user:actualStrategy> <user:interests> <user:string>tax</user:string> <user:string>international</user:string> </user:interests> <user:id>747</user:id> <user:fundList> <user:string>/repositories/Funds/en_US/overseas.xml</user:string> <user:string>/repositories/Funds/en_US/moneymarket.xml</user:string> <user:string>/repositories/Funds/en_US/growth.xml</user:string> <user:string>/repositories/Funds/en_US/growthincome.xml</user:string> </user:fundList> <user:email>sandy@example.com</user:email> <user:password>d686a53fb86a6c31fa6faa1d9333267e</user:password> <user:registrationDate>1999-04-15T00:00:00.0</user:registrationDate> <user:userType>investor</user:userType> <user:member>true</user:member> <user:brokerId>734</user:brokerId> <user:numberFeatureItems>3</user:numberFeatureItems> <user:login>sandy</user:login>

1 Creating and Using Web Services 31

<user:guests>false</user:guests> <user:brokers>false</user:brokers> <user:investors>true</user:investors></user:user>

Notice that information about the XML Schema for this data is included in the user:user tag at the beginning

of the document:

xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd "

The xsi:schemaLocation attribute specifies the URL and name of the Schema file. The Schema

filename (profileMapping+UserProfiles+user.xsd) is determined by the name of the mapping file

(profileMapping.xml), the name of the repository (UserProfiles), and the item descriptor (user). If no

mapping file is used to create the document, the Schema filename indicates the repository and item descriptor.

If you want the Schema filename to include the entire pathname, set the appendRelativeSchemaLocation

property of the GetService component to true. This is especially important if you’re using an external Schema

verification tool, which will generally need the complete pathname to find the Schema file.

If you use a mapping file when you create an instance document, you should be sure to supply the name of this

mapping file to the generateXMLSchema command (using the –mappingFile argument) when you generate

the Schema. Otherwise the actual Schema filename will not match the name in the xsi:schemaLocation

tag, and the Schema may not accurately reflect the data in the instance document; as a result, you may not

be able to validate the data when reading it into a remote system (or reading it back into Dynamo using

AddService). Note also that if your call to getItemAsXML() includes an input argument that specifies the

names of properties to write out, the Schema will not accurately reflect the data in the instance document, so

validation will not be possible.

To avoid any conflict between tag names, the XML tags in the generated instance document are named

using the convention itemType:propertyName; for example the user:userType tag stores the value

of the userType property of the user item type. If the addItemTypeToPropertyNames property of the

RepositoryXMLTools component that GetService points to is set to true, the tags are named using the

convention itemType:itemType.propertyName; in this case, the tag name would be user:user.userType.

By default addItemTypeToPropertyNames is set to true, because the resulting XML is less likely to result in

naming collisions.

Adding Repository Items

You use the addItem() method of the atg.repository.xml.AddService class to create new

repository items from XML documents. This method takes an XML document as an input argument and

returns a repository item. The XML document can be in the form of a String, a java.io.Reader, or a

java.io.InputStream. The method examines the schemaLocation attribute in the XML document to

determine if there is a mapping file associated with the document. Some versions of the method take additional

arguments for specifying how to handle missing or empty tags, and whether the data should be validated

against a Schema.

For some examples of how a repository item might look in XML document form, see the <ATG11dir>/

RL/Example/j2ee-apps/example/web-app/public directory. The Repository Loader (RL) module also

includes a page you can use to generate XML documents from existing repository items. This page is located at

<ATG11dir>/RL/Example/j2ee-apps/example/web-app/itemAsXml.jsp.

Note that addItem() cannot create new read-only elements in a repository. By default, any data in the instance

document that corresponds to a read-only element in the repository is silently ignored. If you want addItem()

to log a warning each time it skips a read-only element, set the logWarningOnReadOnly property of the

AddService component to true.

32 1 Creating and Using Web Services

Validating Repository Item Data

The addItem() method can optionally validate the data in an XML instance document against the Schema

specified in the instance document. Validation is enabled or disabled by the validate property of the

AddService component. By default, this property is set to false, because validation slows down processing of

the document. To enable validation, set the validate property to true.

The addItem() method can also take a Boolean argument to specify whether to validate the document. The

value of this argument overrides the validate property. If you do not specify this argument, addItem() uses

the validate property to determine whether to validate the document.

If you are confident that your data is valid, you can disable validation, and the instance document will be

processed more quickly. However, if the data turns out to be invalid, the invalid data may be written to the

repository. If you enable validation and the data is invalid, addItem() does not write the contents of the

instance document to the repository.

Updating Repository Items

You use the updateItem() method of the atg.repository.xml.UpdateService class to modify a

repository item. For example, the following instance document updates a user’s email address:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress></user:user>

The updateItem() method can optionally validate the instance document against the specified Schema.

The logic for this is similar to the AddService.addItem() method: the UpdateService component has

a validate property whose default value is false, and the updateItem() method can take a Boolean

argument that overrides the value of the validate property.

See Selecting Repository Items to Update (page 32) and Using the repositoryId Attribute (page 34).

Selecting Repository Items to Update

There are two ways to select the item to update:

• You can specify the item explicitly when you call updateItem()

• You can specify a set of match properties, and updateItem() selects the item whose values match the

corresponding values in the instance document

For example, the login property is often used for matching, because it is unique to a specific user item and its

value does not change. The following XML instance document could be used to select the item and then update

its emailAddress property:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress> <user:user.login>sandy</user:user.login></user:user>

1 Creating and Using Web Services 33

The application would then use the following code to update the user repository item whose login value is

sandy (assuming the inputXML String contains the instance document shown above):

String[] matchProperties = {"login"};RepositoryItem updatedItem = UpdateService.updateItem(inputXML, matchProperties);

Note that UpdateService determines the repository and item type from the namespace of the instance

document. See Getting Repository Items (page 29).

The matchProperties array can contain any number of property names. If the value of each repository item

property named in matchProperties matches its corresponding attribute in the XML instance document, the

item is selected for update. All of the specified properties must match for the item to be selected; for example, if

matchProperties lists login and lastName properties, the values of both properties must match. If multiple

items are selected, an exception is thrown and no update occurs.

Matching is limited to top-level properties of the repository item. Subproperties (such as properties of other

repository items) cannot be matched. So, for example, if a user item has a lastName property that is a String,

you can include lastName in matchProperties; but if a user item has a shippingAddress property that is

another repository item, you cannot include, say, shippingAddress.city in matchProperties.

If a property has been mapped to a different name in the instance document, the name to match on is the

property name used in the repository, not the instance document. For example, suppose you use a mapping file

to map a user item’s dateOfBirth property to the name birthday, like this:

<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true"> <property name="dateOfBirth" targetName="birthday"/>

The corresponding instance document might look like this:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.birthday>02-06-1975</user:user.birthday></user:user>

To specify this property in matchProperties, you use the name of the property as it is defined in the repository

(dateOfBirth), not the target name (birthday). For example:

String[] matchProperties = {"dateOfBirth"};

You can configure the UpdateService to add a repository item if an attempt to update does not find a match.

If you want the UpdateService to add items when no items are matched, set the addWhenNoMatchedItems

property of the UpdateService to true.

If the property being updated is a simple type (such as a String), then its value is updated by the

UpdateService. When the property being updated is a list, map or array, then the old value is replaced by the

new value. The new value is not appended to the old value. If the property being updated is an item descriptor,

then the appropriate fields of the existing item descriptors are updated.

34 1 Creating and Using Web Services

Using the repositoryId Attribute

The repositoryId attribute of an item can be used as a special match property. If the repositoryId String

is passed to UpdateService as a match property, the service will determine the value of this attribute from the

top-level XML element in the instance document, and then find a repository item with a matching repository ID.

The following XML example uses the repositoryId attribute as a match property:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747" repositoryId="user707"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress></user:user>String[] matchProperties = {"repositoryId"};RepositoryItem updatedItem = UpdateService.updateItem(inputXML, matchProperties);

In this case, the UpdateService selects the user item whose repositoryId is “user707” from /atg/

userprofiling/ProfileAdapterRepository.

Note: Do not confuse with the repositoryId attribute, which identifies a repository item, with the ID attribute

used in the XML schema to identify an XML element. The repositoryId attribute and not the ID attribute is

used to identify which repository item to update.

Removing Repository Items

You use the removeItems() method of the atg.repository.xml.RemoveService class to delete repository

items specified in XML documents. This method takes an XML document in the form of a String array, a

java.io.Reader, or a java.io.inputStream.

Some versions of removeItems() take a matchProperties String array. Property matching for

RemoveService.removeItems() uses the same logic as UpdateService.updateItem(), except it is legal

for multiple repository items to be marked for deletion. For example, an instance document to remove all users

whose date of birth is 02-06-1975 would look like:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.dateOfBirth>02-06-1975</user:user.dateOfBirth></user:user>

The application then uses the following code to remove all the user repository items whose dateOfBirth value

is 02-06-1975 (assuming the inputXML String contains the instance document shown above):

String[] matchProperties = {"dateOfBirth"};String[] removedItemIds = RemoveService.removeItem(inputXML,matchProperties);

The maximum number of matching items is specified by the maxSelectedItems property of RemoveService.

If the number of matching repository items exceeds this value, an exception is thrown. In the /atg/

repository/xml/RemoveService component, maxSelectedItems is set to 5 by default.

1 Creating and Using Web Services 35

Accessing Web Services from Java Clients

The Oracle Commerce Platform permits external Java clients to access Nucleus methods by exposing them as

Web Services. Many such Web Services are included with the Oracle Commerce Platform, as are tools for creating

custom Web Services. For a list of these Web Services, see Web Services (page 2). Java clients can execute

those Web Services through calls that are translated into XML wrapped in SOAP, transmitted to the Oracle

Commerce Platform, and routed to the Nucleus method itself. Other Oracle Commerce Platform resources, such

as JMS messages and RepositoryItems, can also be exposed as Web Services.

The Oracle Commerce Platform implementation of Web Services follows the standard Web Service guidelines

outlined by JAX-RPC 1.0 and SOAP 1.1 specifications. You may use Apache Axis 1.4 to create your Web Service

calls, and this section includes code examples that assume you are using Axis.

This section aims to inform you how to call Web Services from an Axis client. Rather than provide a broad

discussion on how to use Axis, this section describes Oracle Commerce Platform-specific features and processes

that you need to be familiar with. Please see the Axis documentation for comprehensive instructions.

To access a Web Service, you need to be familiar with the following topics:

About Web Services (page 35)

Before You Begin Using a Java Client (page 36)

Writing a CookieContainer Class (page 37)

Calling Web Services from a Java Client (page 39)

Creating a Serializer and Deserializer (page 42)

About Web Services

For the most part, you call Oracle Commerce Platform Web Services in the same way you call Web Services

elsewhere. While the general process may not differ, it’s important that you are aware of these platform-specific

features.

Security

The content you see as a response to a Web Service call depends on your access privileges. When you login

using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent

Web Service calls in that session are associated with that identity and related role.

For more information on loginUser, see the Personalization Programming Guide. You may also want to learn

how other Web Services handle the security information provided by loginUser. Such information exists in the

Repository Guide and the Core Commerce Programming Guide.

Transactions

When a client calls a Web Service, the transactional behavior of the service is managed entirely on the server

side. The method that is exposed as a Web Service can use standard transaction demarcation techniques, but

the calling client has no control over this.

There are some practical considerations you should be aware of. If a single Web Service call attempts to perform

some operation, and the operation fails, the operation can be rolled back (provided that the Nucleus method

is demarcated properly). However, a transaction cannot span multiple Web Service calls so if an operation

is performed by a sequence of Web Service calls, and the final call fails, there is no way to roll back the steps

performed by the previous calls.

36 1 Creating and Using Web Services

Sharing Sessions

When you create a Web Service, you specify whether it should be executed within the context of an HTTP

session. Associating Web Services with a session enables an application to maintain state across Web Service

calls and to use login information for security purposes.

To allow multiple Web Services to share a session, two things need to happen:

1. The Web Service client must allow a session to be shared across certain Web Service calls. To do this, the client

must pass a session cookie between calls.

2. The Web Services themselves must support sessions. When you create custom Web Services, the Web Service

Creation Wizard gives you the option of supporting sessions.

This section includes an example of a helper class that you can use to simplify cookie management. See Writing

a CookieContainer Class (page 37).

RepositoryItems

If your Web Services access RepositoryItems, you need to provide a serializer and deserializer so the

RepositoryItem content can be interpreted by non-Oracle Commerce Platform systems. The following Web

Services transmit content that is natively stored as RepositoryItems:

• getProfile

• getRepositoryItem

• performRQLQuery

• getOrderAsXML (Core Commerce users only)

• getOrdersAsXML (Core Commerce users only)

• getProductXMLById (Core Commerce users only)

• getProductXMLByDescription (Core Commerce users only)

• getProductXMLByRQL (Core Commerce users only)

• getProductSkusXML (Core Commerce users only)

• getPromotionsAsXML (Core Commerce users only)

The Oracle Commerce Platform includes several tools for working with RepositoryItems. To make a client able

to serialize and deserialize RepositoryItems, you need to translate the RepositoryItem class into a language

that’s native to your client. See Creating a Serializer and Deserializer (page 42) for more information.

Before You Begin Using a Java Client

Before you can access a Web Service, you need to make sure the Oracle Commerce Platform is ready for your call

and Axis 1.4 is configured:

1. Confirm that the application that includes the Web Service is deployed on your application server and is

running. For more information, see Deploying Web Services (page 13).

2. Download Axis 1.4 from the Apache Web site:

http://ws.apache.org/axis

3. Extract the contents of the Axis download file.

1 Creating and Using Web Services 37

4. Add the axis libraries to your CLASSPATH.

See the Apache site for more information about using Axis.

Writing a CookieContainer Class

The following example shows a sample CookieContainer class. You can use this as a model for your own class.

Note that:

• This class relies on the Axis API. If you are using a different Java client, you will need to use the API for your

client

• This class works with both static and dynamic Web Service calls. (See Calling Web Services from a Java

Client (page 39).) If you always make only one of these call types, your own CookieContainer class does

not need to handle both cases

package com.example.webservice;

import org.apache.axis.MessageContext;import org.apache.axis.client.Call;import org.apache.axis.client.Stub;import org.apache.axis.transport.http.HTTPConstants;

/** * A class that can be passed between web service clients that keeps track of * the cookies received from the server. These cookies are then used by * subsequent web service client calls in order to ensure that session * state is maintained.**/public class CookieContainer{ //------------------------------------- // Member variables //-------------------------------------

/** Array of cookies from the Set-Cookie HTTP header **/ private String[] mCookies = null;

/** Array of cookies from the Set-Cookie2 HTTP header **/ private String[] mCookies2 = null;

//------------------------------------- // Methods //-------------------------------------

/** * Gets the cookies set by the Set-Cookie HTTP header * @return the cookies from the Set-Cookie HTTP header, which * may be null **/ public String[] getCookies() { return mCookies; }

/** * Gets the cookies set by the Set-Cookie2 HTTP header * @return the cookies from the Set-Cookie2 HTTP header, which * may be null

38 1 Creating and Using Web Services

**/ public String[] getCookies2() { return mCookies2; }

/** * Extracts the cookies from the given Axis MessageContext, and * sets the cookies and cookies2 properties from them. * @param pContext the Axis message context to examine. This * cannot be null **/ public void extractCookies(MessageContext pContext) { mCookies = (String[])pContext.getProperty (HTTPConstants.HEADER_COOKIE); mCookies2 = (String[])pContext.getProperty (HTTPConstants.HEADER_COOKIE2); }

/** * Extracts the cookies from the given Axis Call, and * sets the cookies and cookies2 properties from them. * @param pCall the Axis call to examine. This * cannot be null **/ public void extractCookies(Call pCall) { extractCookies(pCall.getMessageContext()); }

/** * Extracts the cookies from the given Axis Stub, and * sets the cookies and cookies2 properties from them. * @param pStub the Axis stub to examine. This * cannot be null **/ public void extractCookies(Stub pStub) { extractCookies(pStub._getCall()); }

/** * Pushes the cookie values that are set on the instance to * the given Call * @param pCall the call to set the cookies on. This cannot be null **/ public void pushCookies(Call pCall) { if(mCookies != null) pCall.setProperty(HTTPConstants.HEADER_COOKIE, mCookies); if(mCookies2 != null) pCall.setProperty(HTTPConstants.HEADER_COOKIE2, mCookies2); }

/** * Pushes the cookie values that are set on the instance to * the given Stub * @param pStub the stub to set the cookies on. This cannot be null **/ public void pushCookies(Stub pStub) { if(mCookies != null) pStub._setProperty(HTTPConstants.HEADER_COOKIE, mCookies); if(mCookies2 != null) pStub._setProperty(HTTPConstants.HEADER_COOKIE2, mCookies2);

1 Creating and Using Web Services 39

}}

Calling Web Services from a Java Client

When you call a Web Service, you create resources that describe the Web Service you want to call, its location,

and initial inputs. Axis then takes those resources and produces from them a SOAP message that it then sends to

the Web Service itself.

There are two ways to create a Web Service call:

• Use a client stub to create a static Web Service call

• Use the Dynamic Invocation Interface to create a dynamic Web Service call

The main distinction between the two processes is the data types they can handle. Because using Web Services

requires that data be converted into several formats — from a native format into an XML representation of that

format back into the native form — it is important that you choose a process designed to work with the data

types accessed by the Web Services you want to employ.

The static process can handle any data type regardless of whether it’s primitive, complex, object, or non-

standard. Non-standard types may require some extra effort as is the case when accessing RepositoryItems

or JMS messages. The dynamic process, conversely, is limited to only working with object versions of these data

types (as permitted by SOAP 1.1):

• Boolean

• Byte

• Double

• Float

• Int

• Long

• Short

Some complex types such as Array, List, Set, and Map may be supported using the dynamic process in a

restricted way. See the JAX-RPC Specification for details on data type restrictions.

The subsequent sections describe how you would make a call to the loginUser Web Service following the

static and dynamic processes.

Creating a Call Using a Client Stub (Static)

When you create a call following the static method, you represent the server-side Web Service architecture on

the client by creating a client stub and a client:

• The client stub describes the associated Web Services resources as well as the remote procedure call that the

Web Service executes

• The client configures a particular Web Service instance by specifying initial values and methods on various

Web Services resources

The call is constructed by compiling information from the client stub, client, and various other supporting

classes that hold static information.

40 1 Creating and Using Web Services

For example, to create a static call to the loginUser Web Service:

1. Create and compile the client stub, if one does not already exist for the Web Service. See Creating and

Compiling a Client Stub (page 40) below.

2. Add the client stub to the CLASSPATH variable so the client stub is available to local Web Services resources.

3. Create and compile the client. See Creating and Compiling a Client (page 40) below.

4. Use Axis to execute the Web Service call:

loginStub.createUser(pProfileAsXML)

The format of this call is:

clientStub.web_service(generated_web_Service_Call_instance)

Axis creates the XML message, wraps it in SOAP, and sends it via HTTP to the Web Service location in the client

stub.

See Creating and Compiling a Client Stub (page 40) and Creating and Compiling a Client (page 40).

Creating and Compiling a Client Stub

The client stub describes the Web Service method and supporting resources in a structure that’s familiar to the

client. Each Web Service requires a stub for each client that executes it. You can reuse a stub for subsequent calls

so you only need to create it once. However, simultaneous calls to a Web Service made by different threads will

require that a unique client stub instance exists for each thread.

To create and compile a client stub for the loginUser Web Service:

1. Locate the active WSDL file via HTTP for the Web Service you want to call. The URL is provided in with the

documentation that describes each Web Service:

• For Repository Web Services, see the Repository Guide

• For Oracle Commerce Personalization Web Services, see the Personalization Programming Guide

• For Core Commerce Web Services, see the Core Commerce Programming Guide

It’s important that you access the runtime and not the static version of the WSDL document. Assuming

that you included the modules holding the Web Services you want to access when you assembled your

application, you should be able to download the runtime version of the WSDL.

2. Use the Axis WSDL-to-Java tool to generate the client stub based on the WSDL.

3. Compile the client stub.

Creating and Compiling a Client

A Web Service client is a Java file that describes precisely what the Web Service should do. It provides the actions

the Web Service should commit and initial values.

If you want to enable Web Services to share sessions, your code needs to pass cookies between calls.

The following example, which creates a static Web Service call to the loginUser Web Service, uses the

CookieContainer class shown in Writing a CookieContainer Class (page 37):

{ LoginUserSEIService loginService = new LoginUserSEIServiceLocator();

1 Creating and Using Web Services 41

LoginUserSEI loginStub = loginService.getLoginUserSEIPort(); org.apache.axis.client.Stub axisStub = (org.apache.axis.client.Stub) loginStub; CookieContainer cookieContainer = new CookieContainer();

axisStub.setMaintainSession(true); // Don't allow XML elements to reference other XML elements axisStub._setPropertyValue(AxisEngine.PROP_DOMULTIREFS, new Boolean(false)); // Push cookies onto the Stub cookieContainer.pushCookies(stub);

String userId = loginStub.loginUser("bhavern", " xyo8bnif", false);

// Get cookies out of the Stub, and pass them to subsequent calls as needed cookieContainer.extractCookies(stub);}

Creating a Call Using the Dynamic Invocation Interface (Dynamic)

A dynamic Web Service call holds all relevant information in one file, the client, which Axis converts directly into

the SOAP message. Essentially, the client you create is a Java version of the call itself, excluding some relative

values that are replaced with absolute ones at compile time.

Keep in mind that if you want to access a Web Service that uses non-standard data types, you need to create

your Web Service call following the static process. See Creating a Call Using a Client Stub (Static) (page 39).

If you want to enable Web Services to share sessions, your code needs to pass cookies between calls. The

following example, which creates a dynamic Web Service call to the loginUser Web Service, uses the

CookieContainer class shown in Writing a CookieContainer Class (page 37):

Service service = new Service();Call call = (Call) service.createCall();

// Get a hold of a CookieContainer passed to this method/classCookieContainer cookieContainer = new CookieContainer();

// Push previous cookies (if any) to the new Call objectcookieContainer.pushCookies(call);call.setMaintainSession(true);

call.setTargetEndpointAddress(newjava.net.URL("http://hostname:port/userprofiling/usersession/loginUser/loginUser") );

// Don't allow XML elements to reference other XML elementscall.setProperty(AxisEngine.PROP_DOMULTIREFS,Boolean.FALSE)

call.addParameter("Login", org.apache.axis.Constants.XSD_STRING, javax.xml.rpc.ParameterMode.IN);call.addParameter("Password", org.apache.axis.Constants.XSD_STRING, javax.xml.rpc.ParameterMode.IN);call.addParameter("IsPasswordEncrypted", org.apache.axis.Constants.XSD_BOOLEAN, javax.xml.rpc.ParameterMode.IN);call.setReturnType(org.apache.axis.Constants.XSD_STRING);call.setOperationName(new QName("http://www.atg.com/webservices", "loginUser"));

42 1 Creating and Using Web Services

String userId = (String) call.invoke( new Object[] { "bhavern", "xyo8bnif", Boolean.FALSE } );

// Extract new cookies from the Call into the CookieContainer object,// which can then be passed to subsequent callscookieContainer.extractCookies(call);}

Creating a Serializer and Deserializer

When you want to use a Web Service that accesses RepositoryItems, you can create a mechanism for

translating foreign content into different formats:

• A serializer will convert content from a native format into XML that will eventually undergo another

conversion into a RepositoryItem. You need to create a serializer for “set” operations in which the client

sends content to the Web Service in the context of the call

• A deserializer constructs XML content that was originally formatted as RepositoryItems into a native

content format. You need to create a deserializer for “get” operations in which a Web call returns content that

represents a RepositoryItem

Both a serializer and a deserializer will need to understand the RepositoryItem schema. When you create

the XML schema and a mapping file, you need information about the Web Service itself. You can find that

information in the sections that describe the Web Service:

• For getProfile, see the Personalization Programming Guide

• For getOrderAsXML, getOrdersAsXML, getProductXMLById, getProductXMLByDescription,

getProductXMLByRQL, getProductSkusXML, getPromotionAsXML, see the Core Commerce Programming

Guide

• For Repository Web Services , see the Repository Guide

Two Repository Web Services, getRepositoryItem and performRQLQuery, require a serializer and

deserializer, but they can apply to any RepositoryItems you choose, which is different from the other Web

Services that are only available to specific RepositorityItems and item descriptors.

The serializers and deserializers you create require a Repository schema, which you can create by following these

steps:

1. Create a Mapping file that determines which RepositoryItem properties will be captured by the Web

Service and returned by the call. See Creating a Mapping File (page 42).

2. Use the generateXMLSchema tool to convert the RepositoryItem class into a standard XML schema. See

Generating an XML Schema (page 43).

3. Insert a reference to the XML schema in your instance document, which is a document that represents an

instance of the Web Service call. You complete this step when you configure the client stub; see Creating and

Compiling a Client Stub (page 40) for instructions.

Creating a Mapping File

If you were to create an XML schema that included all RepositoryItem properties, some content may not

be understood by standard deserializers and some may not conform to the XML 1.0 specification. Instead,

you create a mapping file that determines which properties, from the RepositoryItem's item descriptor,

to include or exclude from your XML schema. For instructions on how to create a mapping file, see Mapping

Files (page 22).

1 Creating and Using Web Services 43

To create a mapping file, you need to know the properties defined by your item descriptor so you can decide

which of them ought to be represented in the XML schema. You can find the location of a Repository’s item

descriptor in the Oracle Commerce Platform Dynamo Server Admin UI:

1. In the Dynamo Server Admin, click the Component Browser link.

2. Navigate to the Repository component that correlates to your Web Service as indicated in the appropriate

documentation for the Web Service.

3. Click the See Property Descriptions link beside the item descriptor name. For the item descriptor name, see

the documentation for your Oracle Commerce Platform application’s Web Service.

This list that displays includes all properties that are available to the item descriptor based on the modules

that are currently running.

To make this XML schema compatible with the expectations of the resources that will use it, exclude the

following items from your XML schema:

• RepositoryItem properties that accept primitive data types and may be null

• RepositoryItem properties that accept Maps, Lists, or Sets

Generating an XML Schema

The generateXMLSchema is a script that takes a given Repository component and item descriptor as arguments

and produces an XML schema. For instructions on using this tools, see XML Schemas (page 27).

When you create an XML schema in support of a Web Service, make sure that the same modules in the Oracle

Commerce Platform are running now as those that will be running when the client calls the Web Service.

For a list of Web Services, associated Repository components and items descriptors, see the documentation for

the Web Service.

You may find these two optional arguments helpful:

• outputDirectory copies the resultant XML schema to the directory of your choosing

• mappingFile specifies a file that describes the RepositoryItem properties to include in the resultant XML

schema

Other Required Schemas

When a client deserializes a RepositoryItem, it uses the schema derived from the item descriptor to

reconstruct each repository object and its properties in the appropriate data types. Depending on the makeup

of the item descriptor, you may need to also generate a schema for related item descriptors.

Consider the Profile repository that uses the user item descriptor. There are two item descriptors, broker

and investor, that are subtypes of user. If you were to use the updateProfile Web Service call while

the Relationship Management platform is running, user and all subtypes of it that are part of Relationship

Management are accessible. When you call updateProfile, it’s unclear which version of user you want to call:

user, investor or broker. In this case, you need to generate XML schemes for all three item descriptors.

In short, you need to generate an XML schema for all item descriptors used by RepositoryItems that are

accessed by a Web Service call and for any related (parent or child) item descriptors that are running when the

call is made.

It is difficult to supply a general list of all item descriptors for which this added step applies because the contents

of that list depend on many factors. When deciding if you need to create supplemental XML schemas for an item

descriptor, consider the following:

44 1 Creating and Using Web Services

• The Web Service you are calling

• The modules running when you call that Web Service

• The contents of your Oracle Commerce Platform module stack

• The custom Oracle Commerce Platform components you have created that may extend existing components

accessed by the Web Service

Note: The previous discussion addresses item descriptors and their subtypes, meaning item descriptors that

inherit from the parent class. This relationship should not be confused with that which item descriptors share

with extensions of themselves, which are added by other modules. For example, the order item descriptor has

one set of properties provided by the Oracle Commerce Core Commerce consumer-based module. A second

order item descriptor is supplied by Core Commerce for business users and, when both modules are running,

the order item descriptors are concatenated so that Core Commerce properties for businesses take precedence.

Because all versions of order for the running module are combined into one, you need only one XML schema

for the order item descriptor. When you create that XML schema for order, remember to do so while the same

modules are running as will run when your Web Service calls that item descriptor.

Accessing Web Services from .NET Clients

The Oracle Commerce Platform permits .NET clients to access Nucleus methods by exposing them as Web

Services. There are many Web Services included with the Oracle Commerce Platform, as are tools for creating

custom Web Services. For a list of Oracle Commerce Platform Web Services, see Web Services (page 2). .NET

clients are able to contact those Web Services through a carefully constructed call that’s built in .NET, translated

into XML wrapped in SOAP, transmitted to the Oracle Commerce Platform, and routed to the Nucleus method

itself. Other Oracle Commerce Platform resources, such as JMS messages and RepositoryItems can also be

exposed as Web Services.

This section describes how to call Web Services from a .NET client. Rather than provide a broad discussion on

how to use .NET, this section describes Oracle Commerce Platform-specific features and processes that you need

to be familiar with. Please see your .NET documentation for comprehensive instructions.

To access a Web Service, you need to be familiar with the following topics:

About Web Services in the Oracle Commerce Platform (page 44)

Before You Begin Using a .NET Client (page 46)

Calling Web Services from a .NET Client (page 47)

Using the Atg.DotNet.WebService API with RepositoryItems (page 49)

About Web Services in the Oracle Commerce Platform

For the most part, you call Web Services in the same way you call Web Services elsewhere. While the general

process may not differ, it’s important that you are aware of these platform-specific features.

Security

The content you see as a response to a Web Service call depends on your access privileges. When you login

using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent

Web Service calls in that session are associated with that identity and related role.

1 Creating and Using Web Services 45

For more information on loginUser, see the Personalization Programming Guide. You may also want to learn

how other Web Services handle the security information provided by loginUser. Such information exists in the

Repository Guide and the Core Commerce Programming Guide.

Transactions

When a client calls a Web Service, the transactional behavior of the service is managed entirely on the server

side. The method that is exposed as a Web Service can use standard transaction demarcation techniques, but

the calling client has no control over this.

There are some practical considerations you should be aware of. If a single Web Service call attempts to perform

some operation, and the operation fails, the operation can be rolled back (provided that the Nucleus method

is demarcated properly). However, a transaction cannot span multiple Web Service calls so if an operation

is performed by a sequence of Web Service calls, and the final call fails, there is no way to roll back the steps

performed by the previous calls.

Session Sharing

When you create a Web Service, you specify whether it should be executed within the context of an HTTP

session. Associating Web Services with a session enables an application to maintain state across Web Service

calls and to use login information for security purposes.

To allow multiple Web Services to share a session on .NET, two things need to happen:

1. The Web Service client must allow a session to be shared across Web Service calls. To do this, you need to

define the Web Service calls in the same Web Control and assign a CookieContainer for each call. For

instructions, see Calling Web Services from a .NET Client (page 47).

2. The Web Services themselves must support sessions. When you create custom Web Services, the Web Service

Creation Wizard gives you the option of supporting sessions.

Client Stubs

The Oracle Commerce Platform provides preconfigured client stubs for all Web Services in ATGWS.dll. To use

these stubs you need to install ATGWS.dll. See Installing ATGWS.dll (page 46) for instructions. The client

stubs provided here should be sufficient for your Web Services. Note that simultaneous calls to a Web Service

made by different threads will require that a unique client stub instance exist for each thread.

Web Services that Access RepositoryItems

Standard serializers and deserializers can handle some complex types, such as JMS messages sent to the

ContentViewed and ContentRecommended Web Services. When Web Services interact with proprietary

technologies, such as RepositoryItems, standard serializers and deserializers do not understand the source

data type so they are not able to recreate it.

A RepositoryItem is a specialized JavaBean called a Dynamic Bean that produces basic get and set

methods for the fields you define for it. Many complex items are stored by the Oracle Commerce Platform as

RepositoryItems. The following Web Services transmit content that is natively stored as RepositoryItems:

• getProfile

• getRepositoryItem

• performRQLQuery

• getOrderAsXML (Core Commerce users only)

• getOrdersAsXML (Core Commerce users only)

• getProductXMLById (Core Commerce users only)

46 1 Creating and Using Web Services

• getProductXMLByDescription (Core Commerce users only)

• getProductXMLByRQL (Core Commerce users only)

• getProductSkusXML (Core Commerce users only)

• getPromotionsAsXML (Core Commerce users only)

For these Web Services, you can use the Atg.DotNet.WebService API to serialize and deserialize related

content. Descriptions for API classes are in Using the Atg.DotNet.WebService API with RepositoryItems (page

49). You can find this API in ATGWS.dll, which you need to install in order to access them. See Installing

ATGWS.dll (page 46).

Before You Begin Using a .NET Client

Before you can access a Web Service, you need to make sure the Oracle Commerce Platform is ready for your call

and .NET is configured:

1. Confirm that the application that includes the Web Service is deployed on your application server and is

running. For more information, see Deploying Web Services (page 13).

2. Install Internet Information Service (IIS) and then Active Server Page.Net (ASP.NET) and VisualStudio.NET

(VS.NET).

3. Install ATGWS.dll so you can access the stub and API classes it contains.

Installing ATGWS.dll

ATGWS.dll is a library that includes a stub class for each Web Service. It also provides the

Atg.DotNet.WebService API used for serializing and deserializing RepositoryItems. All users who want to

access Web Services from a .NET client should install ATGWS.dll. You need two versions of ATGWS.dll on your

system. One version lives in you Global Assembly Cache (GAC) so ASP.NET is able to access it when compiling the

Web Service call. Another version should exist in a location that VS.NET recognizes.

The instructions provided here direct you to use GACutil, a utility provided by .NET, although you can use any

utility that can install ATGWS.dll to the Assembly folder in your windows directory. While the library does not

need to live on the same machine as .NET, .NET needs to be able to access it.

To install ATGWS.dll:

1. Copy <ATG11dir>/DAS/os_specific_files/i486-unknown-

win32/ATGWS.dll to your Windows\Assembly folder.

2. Open a command prompt and enter the following command:

<DotNetdir>:\ gacutil/i <ATG11dir>/DAS/os_specific_files/i486-unknown-

win32/ATGWS.dll

In this example, <DotNetdir> represents the parent directory, such as c:\DotNet that holds your .NET

software.

Keep in mind that each time you install a new version of ATGWS.dll, it coexists with older versions. The latest

version of ATGWS.dll will instruct the .NET client to use it. There’s no need to uninstall ATGWS.dll when you

want to install a new version. Remember when you do install new versions, you need to update references in

VS.NET to the old version of ATGWS.dll. If you’d like to remove all versions of ATGWS.dll, use this command in

a command prompt:

<DotNetdir> gacutil/u <ATG11dir>/DAS/os_specific_files/i486-unknown-

1 Creating and Using Web Services 47

win32/ATGWS

Calling Web Services from a .NET Client

This section describes the components you need in order to call a Web Service. Because there are a few ways

that you can generate a Web Service call on .NET, this section focuses only on the Oracle Commerce Platform

resources you will use and assumes that you will refer to your .NET documentation for specific instructions.

The following sections should provide guidance when creating a Web Service call:

Accessing a Web Service (page 47)

Accessing a Custom Web Service (page 47)

Sample Web Service Calls (page 47)

Accessing a Web Service

The Oracle Commerce Platform provides client stubs for all Web Services in ATGWS.dll. Once you have

installed a version of ATGWS.dll to your GAC and Assembly folders (see Installing ATGWS.dll (page 46) for

instructions), you need to do two things:

1. In your Visual Studio .NET project, make a reference to ATGWS.dll.

2. Create instances of the client stubs and use them in your Web Service call.

Accessing a Custom Web Service

To access a Web Service that you created in the Oracle Commerce Platform, you create client stub and a

reference to it in your Visual Studio.NET project:

1. Assemble your application. Make sure you include the modules that contain the Web Services you want to

access.

2. Deploy the application on your application server and start it up.

3. In your Visual Studio .NET project, add the Web Services as Web References.

4. When prompted for an Address, provide the WSDL URI, such as:

http://hostname:port/repository/generic/getItem?WSDL

You can find the URI for Web Services in the documentation for the specific Web Service:

• For Repository Web Services, see the Repository Guide

• For Personalization Web Services, see the Personalization Programming Guide

• For Commerce Web Services, see the Core Commerce Programming Guide

Sample Web Service Calls

The Web Service call is a document that incorporates calls to any number of Web Services that may exist in the

same session. For each Web Service, you create an instance of the client stub, call methods on the Web Service,

and call the Web Service itself. These Web Service calls are written in C#.

Simple Call Example

This Web Service call obtains a RepositoryItem by accessing the getRepositoryItem Web Service.

48 1 Creating and Using Web Services

using Atg.DotNet.WebService.Repository.GetRepositoryItem;

// ...

// create stub instance GetRepositoryItemSEIService getItemClientStub = new GetRepositoryItemSEIService(); // assign URL of web service getRepositoryItemClientStub.Url = "http://example.com/repository/generic/getItem/getRepositoryItem"; // call web service string itemXml =getRepositoryItemClientStub.getRepositoryItem("/nucleus/path/to/repository","itemDescriptorName", "repositoryId"http://example.com/repository/generic/getItem/getRepositoryItem

Complex Call Example

The following code demonstrates how you would construct a call that uses security controls to restrict the

information users can access. Notice that the loginUser Web Service establishes the user identity role, which

other Web Services refer to. Because an instance of a CookieContainer is created in this code and assigned to

each Web Service stub, all Web Services called here exist in the same session.

For brevity these examples omit some details such as a exception handling for the SoapException as well as

class syntax.

using System.Net; // for CookieContainerusing Atg.DotNet.WebService.Repository.GetItem;using Atg.DotNet.WebService.Repository.PerformRQLQuery;using Atg.DotNet.WebService.UserSession.LoginUser;using Atg.DotNet.WebService.UserSession.LogoutUser;

// create stub instancesGetItemSEIService getItemClientStub = new GetItemSEIService();PerformRQLQuerySEIService performRQLQueryClientStub = newPerformRQLQuerySEIService();LoginUserSEIService loginUserClientStub = new LoginUserSEIService();LogoutUserSEIService logoutUserClientStub = new LogoutUserSEIService();

// create a new cookie container for our session and share it between// the various stub instancesCookieContainer cookieContainer = new CookieContainer();getItemClientStub.CookieContainer = cookieContainer;performRQLQueryClientStub.CookieContainer = cookieContainer;loginUserClientStub.CookieContainer = cookieContainer;logoutUserClientStub.CookieContainer = cookieContainer;

// authenticate the user for the sessionloginUserClientStub.loginUser("user", "password", false);

// call servicesstring itemXml = getItemClientStub.getItem("/nucleus/path/to/repository", "itemDescriptorName", "repositoryId");string[] itemsXml = performRQLQueryClientStub.performRQLQuery("/nucleus/path/to/repository", "itemDescriptorName", "property = 'value'");

1 Creating and Using Web Services 49

// log out the userlogoutUserClientStub.logoutUser();

Using the Atg.DotNet.WebService API with RepositoryItems

The Atg.DotNet.WebService API is a mechanism that you can use to serialize and deserialize

RepositoryItem content. The primary role of this API is to:

• Converts a RepositoryItem into an XML document (serialization)

• Formats an XML document into a RespositoryItem (deserialization)

By understanding the RepositoryItem API, Atg.DotNetWebService.RepositoryItem is able to convert

into objects any content that uses the RepositoryItem API for its underlying data type. You can use this API for

any Web Services that access RepositoryItems.

The Atg.DotNet.WebService is made up of the following classes:

RepositoryItem Class (page 50)

Property Class (page 51)

RepositoryItemRef Class (page 52)

Complex Type Class (page 52)

NoSuchPropertyException Class (page 53)

RepositoryItemSerializer Class (page 53)

RepositoryItemSerializationException Class (page 54)

Note: Rather than use this API, you could generate an XML schema representation of the RepositoryItem

and use that serialize/deserialize content. The advantage of using an XML schema is that you can control the

properties you use, meaning you can easily exclude certain properties from your schema. You may find the

disadvantages, namely the limitations in property types and values that this method supports, reason to use

the provided API instead. For instructions on how to use an XML schema for serialization/deserialization, see the

Creating a Serializer and Deserializer (page 42).

About the Atg.DotNet.WebService API

Collectively, these classes provide you with the ability to serialize and deserialize RepositoryItems and to

configure both processes. Although this discussion specifically describes the serialization process, the same

principles apply to both processes.

When you want to deserialize content from a Web Service, for example, you use the response sent by a Web

Service resulting from your initial Web Service call. The response, formatted in XML, holds a string object that

represents RepositoryItems. Once you make the call to the API to deserialize the string, the deserializer parses

the string into a RepositoryItem object.

Not all content in the string is emitted by the serializer. By default, only content specified as “dirty,” meaning a

different value for it exists in the Oracle Commerce Platform and the external system .NET communicates with,

is serialized. Once an item has been serialized, there’s parity across systems so all properties on that item are

marked as “clean.” You can alter the default dirty/clean designation in the following ways:

• Use the RepositoryItem.Dirty property to toggle an object’s clean/dirty status

50 1 Creating and Using Web Services

• Use the RepositoryItem.setPropertyDirty() methods to toggle a property’s clean/dirty status

During deserialization, content that represents RepositoryItem properties is parsed based on a few rules. All

properties are converted back to the native data type, assuming that data type is available in .NET. The following

data types do not exist in .NET and so values for these types are converted as follows:

• Map properties use Hashtable data type in .NET

• Date or Timestamp properties are stored as .NET DateTime data type

• Set properties are formatted as .NET Array data type

• Properties that refer to other RepositoryItems behave as .NET Hashtables

For the most part, Atg.DotNet.WebService determines format output type by relying on prior processing.

For example, if it had deserialized a particular RepositoryItem, such a Growth fund, then assuming no new

properties are added, when the Growth fund is serialized, Atg.DotNet.WebService.RepositoryItem is

aware of each property’s destination data type. However, in all other circumstances, you should explicitly include

the XML data type for the property. In short, under these circumstances include data types:

• The first time a RepositoryItem is serialized when it has not been previously deserialized, such as in the case

of adding a new item to the Oracle Commerce Platform

• A new property value is assigned to an empty RepositoryItem

Note: In order to use the classes in this interface, make sure that the Oracle Commerce Platform atg/

repository/xml/RepositoryXMLTools component has the encodeRepositoryIdAsAttr property set to

true. This is the default setting.

RepositoryItem Class

The Atg.DotNet.WebService.RepositoryItem class is designed to manage XML serialization and

deserialization for easy interoperability with the .NET Web Services framework.

To serialize or deserialize a RepositoryItem, you need only to pass in the RepositoryName and

RepositoryId. When you are working with content for the first time, you also need to call setPropertyType

to instruct the deserializer/serializer to use a specific output data type.

Class Element Description

properties Dirty

Determines the overall dirtiness of an object by specifying whether all properties are

clean (false) or one of more properties are dirty (true).

ItemDescriptorName

Name of the item descriptor associated with the object’s RepositoryItem.

Properties

List of properties for this RepositoryItem.

RepositoryId

ID provided to the object’s RepositoryItem representation.

RepositoryName

Name of the repository that the RepositoryItem is part of.

1 Creating and Using Web Services 51

Class Element Description

constructors RepositoryItem()

Constructs a new, empty RepositoryItem object. When you serialize or deserialize

a property with a value that is a pointer to a RepositoryItem, be sure to supply it a

RepositoryName, RepositoryId, and ItemDescriptorName when you invoke the

setRepositoryItem method.

RepositoryItem(string)

Constructs a new RepositoryItem in the Oracle Commerce Platform, populating it with

values parsed from the XML instance of the Web Service call. The XML instance is a by-

product from the Web Service call generation.

methods clearPropertyValues

Clears all property values for a given RepositoryItem. Before using

RepositoryItemSerializer.deserialize, it’s a good idea to use this method to

clear all previous values.

isPropertyDirty

Determines whether a given property value is dirty (true) or clean (false).

setPropertyDirty

Designates a given property as dirty.

getPropertyValue

Returns the value provided for a property in the Oracle Commerce Platform. If the

property does not exist, an error of type ATGWS.NoSuchPropertyException is thrown.

setPropertyValue

Sets a value for a property in the Oracle Commerce Platform.

getPropertyType

Returns the property’s XML data type.

setPropertyType

Specifies the XML data type for the property value.

serialize

Creates a string representation of an XML document for the RepositoryItem.

Property Class

This class represents a given property’s name and value.

52 1 Creating and Using Web Services

Class Element Description

properties Dirty

Determines whether a given property is dirty (true) or clean (false). If you

indicate that a property value should change by invoking the RepsoitoryItem

setPropertyValue call, this property is set to true. Once a response is returned from

the setPropertyValue call, this property is set to false.

XmlType

XML data type that will be used to represent the property’s value.

constructor Property()

Constructs an empty object representing a property.

methods getName

Returns the name of the property.

getValue

Returns the value of the property.

setValue

Sets a new value to the property.

RepositoryItemRef Class

This class represents a reference to another RepositoryItem.

Class Element Description

properties RepositoryName

Name of the repository of which the referenced RepositoryItem is a part.

ItemDescriptorName

Name of the item descriptor used by the referenced RepositoryItem .

RepositoryId

ID for the referenced RepositoryItem .

method setRepositoryItem

Initializes the ItemRef to refer to the provided RepositoryItem.

Complex Type Class

This class permits you to serialize/deserialize properties that use complex types by specifying an output data

type explicitly.

1 Creating and Using Web Services 53

Class Element Description

properties TypeName

Data type for the RepositoryItem property.

Properties

Name of any properties that are either deserialized from or serialized into the complex

type.

constructor ComplexType()

Constructs an empty object to represent all properties of a complex data type.

methods getPropertyValue

Retrieves values from the Oracle Commerce Platform for the specified properties. If the

property does not exist, an error of type ATGWS.NoSuchPropertyException is thrown.

setPropertyValue

Sets a property to a value supplied as an input.

getPropertyType

Returns the XML data type for the property value.

setPropertyType

Specifies the XML data type for the property value.

NoSuchPropertyException Class

This class generates an exception each time a getProperty or getPropertyValue method tries to interact

with a property that has not been specified for the designated RepositoryItem.

Class Element Description

property PropertyName

Name of the property that you are trying to work with.

constructor NoSuchPropertyException

Constructs the exception.

RepositoryItemSerializer Class

This class conducts serialization/deserialization and permits you to decide if you want all or only dirty properties

to be updated.

54 1 Creating and Using Web Services

Class Element Description

constructors RepositoryItemSerializer()

Constructs a serializer instance.

RepositoryItemSerializer(RepositoryItem)

Constructs an object holding serialized content.

methods deserialize (string)

Deserializes an XML-formatted string into a new RepositoryItem.

deserialize (string, boolean)

Deserializes an XML document string into a RepositoryItem. Additional arguments

true or false indicate whether values for only dirty properties (true) or all properties

(false) should be deserialized.

serialize (string)

Serializes a RepositoryItem into an XML-formatted string document.

serialize (boolean)

Serializes a RepositoryItem into an XML document. Additional arguments true and

false indicate whether values for only dirty properties (true) or all properties (false)

should be deserialized.

RepositoryItemSerializationException Class

This class creates an exception object when errors occur during serialization or deserialization.

Class Element Description

constructor RepositoryItemSerializationException()

Constructs an empty exception object.

2 Introduction to REST Web Services 55

2 Introduction to REST Web Services

This section provides information about and instructions for using the Oracle Commerce Platform

Representational State Transfer (REST) Web Services.

Oracle Commerce Platform REST Web Services provide access to Nucleus components. Nucleus components

are server-side JavaBeans and servlets that perform the back-end functionality of a Web application, such as

enabling database connectivity, logging, scheduling, and handling HTTP requests.

Oracle Commerce Platform previously provided a single process that wrote directly to the HTTP response buffer.

This API is identified throughout this guide as the Legacy REST API. The Legacy framework has been enhanced

to provide a Model View Controller (MVC) architecture and framework that supports multiple controllers that

generate a model map that can be filtered. This multiple controller API is known as the REST MVC API.

Note: It is strongly suggested that, if you are creating new REST services, you use the REST MVC API. The Legacy

REST API is limited in its ability to be configured and is not extensible.

This section is divided into three parts:

• Introduction to REST Web Services (this section) describes generic REST Web Services and terminology. This

section also provides information that applies to both the REST MVC Web Services and the Legacy REST Web

Services

• Part I, “Oracle Commerce Platform REST MVC Web Services” (page 67) describes the extensible REST MVC

API, describing the architecture and components that allow you to create REST services, as well as instructions

on creating your own REST services. This section also provides detailed examples of REST services that have

been provided for quick implementation

• Part II, “Legacy REST Web Services” (page 319) describes the Legacy REST API and the components that are

used to develop REST services

REST Web Services Overview

In general, a REST Web Services exposes data and function resources through the use of Uniform Resource

Identifiers (URIs). These resources are used within simple, well-defined operations. HTTP methods are used by

the REST services to point to a resource. Each HTTP request returns an HTTP response, which indicates the status

of the operation. The application that receives the request identifies the format of the response, which is JSON or

XML.

REST clients may be accessed from any browser, and security can be configured for each call.

56 2 Introduction to REST Web Services

REST Web Services URLs

URLs are a central component of REST Web Services, as you access different components and functions of the

Oracle Commerce Platform using specific URLs.

The application path for REST URLs, which is the portion of the URL that follows the hostname and port number,

starts with /rest/. For example, you would use the following URL to initiate adding an item to a shopping cart

using the /atg/commerce/order/purchase/CartModifierActor/addItemToOrder component.

http://servername:port/rest/REST framework type/atg/commerce/order/purchase/CartModifierActor/addItemToOrder

The portion of the application path following /rest/ identifies which version of the Oracle Commerce Platform

REST framework type you are using.

The REST MVC framework uses /model, for example:

http://servername:port/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder

For additional information, refer to The REST MVC Definition Framework (page 71) section.

The Legacy REST framework uses /bean, /repository or /service, depending on the component used. For

example:

http://servername:port/rest/bean/atg/userprofiling/ProfileServices/loginUser?arg1=MyUsername&arg2=MyPassword

http://servername:port/rest/repository/atg/userprofiling/ProfileAdapterRepository/user

For additional information, refer to the Using Legacy REST Web Services (page 321) section. For additional

information on component paths, refer to the Platform Programming Guide.

URLs can supply additional data to the REST Web Service using parameters or form post data. By setting control

parameters, as described in the Adding Control Parameters (page 61) section, or standard query and/or post

2 Introduction to REST Web Services 57

parameters, you can set values, supply arguments to a method, or supply form field values. You use standard

URL query string syntax when adding parameters.

HTTP Request Methods

As discussed earlier, HTTP requests and responses are the way that the Oracle Commerce Platform REST Web

Services communicate. The following HTTP methods are used and supported by Oracle Commerce Platform

REST Web Services:

Method Explanation

GET Use this method to return data.

Examples of the values you may get are repository item and Nucleus component property

values, RQL query results, repository items, and Nucleus components.

POST Use this method to invoke functionality or make changes to your Oracle Commerce Platform

server.

For example, you may invoke methods, update Nucleus component properties, and create

repository items.

PUT (Legacy REST Only) Use this method to make changes to your Oracle Commerce Platform

servers.

For example, you may update repository item and Nucleus component property values.

DELETE (Legacy REST Only) Use this method to remove repository items.

For additional information on these and other HTTP methods, refer to the W3 definitions, available at http://

www.w3.org.

HTTP Status Codes

Whenever an Oracle Commerce Platform REST Web service is called, an HTTP status code is sent to indicate the

result of each request. The HTTP status codes that are used with Oracle Commerce Platform REST Web Services

are:

Code Description

200 (OK) The request was processed successfully. This does not mean that it had the

result you intended. See information about how to determine success or

failure in the instructions for specific operations.

201 (Created) Returned only for POST requests that create repository items. The request

was successful and the repository item was created.

58 2 Introduction to REST Web Services

Code Description

400 (Bad Request) The request could not be completed because the request URL and/or

parameters were improperly formatted.

401 (Unauthorized) The user session does not have the proper security credentials to execute the

method, property, or access the repository for the requested resource.

403 (Forbidden) The specified property has been configured as not writeable via the filtering

configuration.

404 (Not Found) The request could not be completed because it was made for a resource that

does not exist.

410 (Gone) Returned only for DELETE requests that remove repository items. The request

was successful and the repository item was deleted.

500 (Internal Server Error) The request could not be completed because an unexpected exception

occurred.

For additional information on these and other HTTP status codes, refer to the W3 definitions, available at http://

www.w3.org.

Returning Data

Oracle Commerce Platform REST Web Services returns the results of operations that you perform in an HTTP

response message body. The output data can be returned in either JavaScript Object Notation (JSON) or

eXtensible Markup Language (XML) format.

The following example shows output data in JSON format.

{"password": "280001"}

The following example shows output data in XML markup.

<password>280001</password>

You can configure your return output data to be provided in the format you choose by setting the default return

output type on the REST server. Additionally, using the atg-rest-output command, you can override the

default output type. Refer to the Adding Control Parameters (page 61) section for additional information.

For information on configuring output in REST MVC, refer to the Configuring REST MVC Output (page 109)

section. For information on configuring output in Legacy REST, refer to the Returned Data in Legacy REST (page

335) section.

2 Introduction to REST Web Services 59

Using cURL for Examples

The examples in this document use the cURL command-line tool to send and receive HTTP messages. cURL is

shown in these examples because its command-line invocation shows the input and the HTTP activity that takes

place when using the REST Web Services. For additional information about the cURL command-line tool, refer to

http://curl.haxx.se/.

Note: You can use any client software to exchange HTTP messages with REST Web Services. Oracle Commerce

Platform is not associated with the makers of the cURL command-line tool in any way.

The cURL examples use several command-line flags. These flags configure the behavior of the cURL command-

line tool as it makes HTTP requests. The flags are included in examples to better show the HTTP requirements

of the Oracle Commerce Platform REST Web Services interface and to help you reproduce the examples if you

choose to do so.

Writing cURL Examples

When writing an example, use cURL to perform the following:

1. Invoke cURL using the curl command.

2. Identify command components that identify locations, cookie files or write verbose output. Refer to the cURL

Command Components (page 61) table for a list of commonly used commands.

3. Identify the cookie file that the service will write to upon completing an operation.

4. Specify the HTTP communication method with the –X command. Note that for REST MVC, the

communication method is limited to GET and PUT.

5. Indicate that the specified content type should be declared in the HTTP request header by using the –H

command.

6. Identify the content type to use. For information on content types, refer to Setting the Content-Type Value in

REST Services (page 65).

7. Indicate that the following text should be used within the message body of the HTTP request.

8. Provide the parameters and their values to be included within the message body.

9. Identify the REST server and port, as well as the REST call. Note that the REST call, which is indentified using

the http://<servername>… syntax, is included in quotation marks (“ “). Technically, cURL does not require

this, however any parameters that follow an ampersand (&) will not be recognized if the command is not

included in quotation marks.

10.Provide any control parameters. Refer to Adding Control Parameters (page 61) for detailed information.

REST MVC cURL Format

When invoking cURL for REST MVC examples, use the following format:

curl <command component> <cookie file> -H <content type> -d "{ <parameter> :<value>, <parameter> : <value> }" "http://<servername>:<port>/rest/model/

60 2 Introduction to REST Web Services

<REST actor-chain component>/<chain ID>?<control parameter>"

The following is a cURL example of a REST MVC external user log in. This example uses the cookie file

customer_cookies.txt, identifies the content type as JSON, and provides the parameters and their values

that are used by the ProfileActor login actor-chain.

curl -L -v -c customer_cookies.txt -H "Content-Type: application/json"-d "{ "login" : "JohnDoe@example.com" , "password" : "password123" }""http://localhost:8080/rest/model/atg/userprofiling/ProfileActor/login"

Legacy REST cURL Format

When invoking cURL for Legacy REST examples, use the following format:

curl <command component> <cookie file> -X <HTTP communication type>-H <content type> -d "<parameter><arg><value></arg></parameter>""http://<servername>:<port>/rest/bean/<REST service>?<control parameter>"

The following is a cURL example of a Legacy REST external user log in. This example uses the cookie file

cookies.txt, identifies the HTTP communication method of POST and provides the MyUsername and

MyPassword arguments.

curl -v -c cookies.txt -X POST -H "Content-Type: application/xml" \-d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2></parameters>" \"http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser"

Server Response to cURL Examples

A few of the examples that follow will provide specific server responses. An example of this format for this

output may be similar to the following:

{ "shippingGroups": {"Test": { "specialInstructions": {}, "priceInfo": { "amount": 0, "currencyCode": null, "amountIsFinal": false, "discounted": false }, "description": "sg140012", "actualShipDate": null, "submittedDate": null, "state": 0, "locationId": null, "shipOnDate": null, "shippingMethod": "hardgoodShippingGroup",…

2 Introduction to REST Web Services 61

cURL Command Components

The following table lists commonly used cURL commands. For additional information or components, refer to

http://curl.haxx.se/.

Component Explanation

curl Names the program being invoked. The manner in which you invoke the cURL command-

line tool depends on how it has been installed in your environment.

-L Identifies an HTTP Location. If the server reports that the requested page has moved to a

different location (indicated with a Location: header and a 3XX response code), this option

will make cURL redo the request at the new location.

-v Writes verbose output while sending and receiving HTTP messages. This option exposes

more details of the HTTP transaction.

-b Uses cookies stored in the specified file to authenticate the client. In Legacy REST Web

Services, cookies are stored in a file named cookies.txt. The customer_cookies.txt

file is used for external REST MVC calls, and the agent_cookies.txt file is used for agent-

based internal REST MVC calls.

A session identifier must be stored in the file. When cURL logs into the REST Web Services,

the cookies.txt instructs it to write the cookies it receives in that file.

-c This command line option activates the cookie engine that makes cURL record and use

cookies. You can also activate cookies by using the -b cookie option. Using –c provides

the HTTP cookie file where cURL writes all cookies after a completed operation. cURL

writes all cookies previously read from a specified file, as well as all cookies received from

remote server(s). If no cookies are identified, no file will be written.

-X Use the specified HTTP method when communicating with the REST Web Services.

-H Include the specified Content-Type declaration in the HTTP request header. This describes

the nature of the data in the message body of the HTTP request.

-d Include the following content in the message body of the HTTP request.

URL The URL of the REST Web Service that is used in the example.

Note: The HTTP transactions shown in the examples in this document may include specific details of the testing

environment used to produce them. Some details may differ in the HTTP transactions you conduct with the

REST Web Services. For example, the application server version identifiers shown in the HTTP transaction may

not match the application that your Oracle Commerce Platform server uses.

Adding Control Parameters

Include control parameters with HTTP requests to alter the way that the REST Web Services handle them. For

example, if you would like the server to include an identifying string in the response, you can use the atg-

rest-user-input control parameter to specify that identifying string.

62 2 Introduction to REST Web Services

You can include control parameters either in the URL for the REST Web Service or in the message body of a POST

or PUT request.

Note: Several control parameters have equivalent configuration properties. Set these configuration properties

to control the way that REST MVC Web Services are processed by default. See The REST MVC Definition

Framework (page 71).

The following table explains the control parameters recognized by the REST Web Services server. This table also

identifies if the parameter is used in the Legacy REST Web Services or the REST MVC Web Services.

Parameter REST Version Explanation

atg-rest-append-multi-

values

Legacy Only Use this parameter to control whether setting a value

on a repository item property will add the value to an

existing set of values or replace them. This only applies to

repository item properties that hold multiple values.

atg-rest-class-

descriptor

Both Legacy

and MVC

Use this parameter to specify the container and element

Java classes for nested object property values.

atg-rest-class-type Both Legacy

and MVC

Use this parameter to specify a Java class when you are

setting an object property value.

atg-rest-count Legacy Only For requests which return an array or ordered list, adding

this parameter with an integer value allows the caller to

specify the number of elements to return. Used with atg-

rest-index.

atg-rest-depth Legacy Only The number of references to traverse when rendering

output. By default it is zero, which causes only the top

level object to be returned.

atg-rest-form-tag-

priorities

Legacy Only Use this parameter to specify which form handler values

should be processed first.

atg-rest-http-method Legacy Only Use this parameter to send the Legacy REST Web Server a

POST HTTP request but have it process the request as if it

used a different HTTP method.

For example you can use this control parameter to include

message body data in a POST HTTP request but have the

server process the request as if it used the GET method.

Set the value of this parameter to GET, PUT, or DELETE.

atg-rest-index Legacy Only Use this parameter to specify the entry in an array or

ordered list that will be the starting point when that array

or ordered list is returned by the server. Set the value of

the parameter to the integer value of the starting position.

Use this parameter with atg-rest-count.

2 Introduction to REST Web Services 63

Parameter REST Version Explanation

atg-rest-input Both Legacy

and MVC

Use this parameter to override the default input format

configured for the server.

Set the value of this parameter to json or xml.

atg-rest-json-input Legacy Only Use this parameter to control whether the Legacy REST

Web Services server will accept standard JSON markup

for setting collection or map values on repository item

properties.

atg-rest-method Legacy Only Use this parameter to specify the Java method signature

when calling an overloaded method.

This parameter is only needed if two or more instances

of the overloaded method have the same number of

arguments.

atg-rest-null Both Legacy

and MVC

Use this parameter to set the value of a component or

repository item property to null. Set the property and

include this parameter as the new value.

atg-rest-output Both Legacy

and MVC

Use this parameter to override the default output format

configured for the server. Set the value of this parameter

to json or xml.

atg-rest-param-class-

types

Both Legacy

and MVC

Use this parameter to specify the Java classes for

multiple values in JSON functional parameters. The atg-

rest-param-class-types parameter includes three

components, container-class, element-class, and

key-class.

For example, if a functional parameter is a

java.util.ArrayList<String>, set the atg-rest-

param-class-types as shown below.

{'container-class':

'java.util.ArrayList',

'element-class':'java.lang.String'}

Use the key-class attribute when the container-

class implements java.util.Map. For example:

{'container-class':'java.util.HashMap',

'key-class':'java.lang.String',

'element-class':'java.lang.String'}

atg-rest-property-

filters

Legacy Only Use this parameter to apply property filtering to individual

Legacy REST Web Services Requests.

atg-rest-property-

filter-templates

Legacy Only Use this parameter to apply property filter templates to

individual REST Web Services Requests.

64 2 Introduction to REST Web Services

Parameter REST Version Explanation

atg-rest-return-form-

handler-exceptions

Legacy Only Use this parameter to specify that the Legacy REST Web

Services server should return exceptions it encounters

when invoking form handlers in the HTTP response.

atg-rest-return-form-

handler-properties

Legacy Only Use this parameter to specify that the Legacy REST Web

Services server should return the properties of the form

handler objects it invokes in the HTTP response.

atg-rest-rql Legacy Only Include RQL query strings in this parameter.

atg-rest-simple-

response-codes

Legacy Only Include this parameter to cause the server to return OK

(200) for success rather than CREATED (201) or GONE

(410).

atg-rest-transient Legacy Only Use this parameter to create transient repository items.

Include the parameter with the value true with a Legacy

REST Web Services request to create a repository item.

atg-rest-user-input Both Legacy

and MVC

Use this parameter to specify an identifying string that

the REST Web Services server will include in the HTTP

response.

Functional Parameters for Oracle Commerce Platform

REST Web Services

Functional parameters provide data that is required by the Oracle Commerce Platform REST Web Services

operation you are performing. For example, if you are setting a property value, the new value is a functional

parameter of the operation.

You can include functional parameters either in the URL for the Oracle Commerce Platform REST Web Service or

in the message body of a POST or PUT request.

The functional parameters you provide for an Oracle Commerce Platform REST Web Services operation depend

on the nature of that operation. When invoking a method, you may supply arguments to it. When invoking

a form handler, you will supply the form field values. When setting a repository item property value, you will

supply the new value. The functional parameters for each operation are explained in the procedures for those

operations.

Using Positional Parameters

Some Oracle Commerce Platform REST Web Services operations require parameters that are not named. For

example, if you invoke the loginUser method of the /atg/userprofiling/ProfileServices component

you must pass in two positional arguments. The first is the login value for a user and the second is the

password value for that user.

2 Introduction to REST Web Services 65

Using URL Parameters

You can include control and functional parameters in the URL for Oracle Commerce Platform REST Web Services

by using standard URL query string syntax and URL encoding. The following Oracle Commerce Platform MVC

REST example shows a URL with two functional parameters and a control parameter.

http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/login?login=JohnDoe@example.com&password=1234&atg-rest-user-input=MyMessageId

Using Message Body Parameters

You can include control and functional parameters in the HTTP message body of an Oracle Commerce Platform

REST Web Services request. The following HTTP request includes two functional parameters and a control

parameter in its message body. The content in the message body is specified by the -d flag in this cURL

command.

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"-d "{ "login" : "JohnDoe@example.com" , "password" : "password123" }""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/login?atg-rest-user-input=MyMessageId"

The Oracle Commerce Platform REST Web Services server can interpret message body parameters in one of the

following three markup formats. Make sure you set the correct Content-Type value for the markup that you

use.

• XML

• JSON

• URL query string in Legacy REST

• Note: The Legacy REST Web Services server will only accept parameters in the message body of a POST or

PUT HTTP request. If you need to use the GET or DELETE methods, you need to include data with your request,

and you cannot include URL parameters, use the atg-rest-view and atg-rest-http-method control

parameters. See Handling POST Requests as Other Methods (page 322).

Setting the Content-Type Value in REST Services

Set the Content-Type value when you send an HTTP message with parameters in its message body. The Oracle

Commerce Platform REST Web Services server uses this value to determine how to interpret the parameters. If

you do not include the Content-Type or include a value that does not match the markup of your parameters,

the server will ignore the message body.

Use one of the following Content-Type values to specify the markup of the parameters in a message body.

• Content-Type: application/xml

• Content-Type: application/json

• Content-Type: application/x-www-form-urlencoded

The following REST MVC example shows an HTTP request that sets its Content-Type to application/xml.

66 2 Introduction to REST Web Services

curl -L -v -b customer_cookies.txt -H "Content-Type: application/xml"-d "{ "login" : "JohnDoe@example.com" , "password" : "password123" }""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/login?atg-rest-user-input=MyMessageId"

Using Array Types

To specify an array type in the atg-rest-class-descriptor control parameter, use the standard Java

notation for arrays.

Array Type Java Notation

String [Ljava.lang.String;

byte [B

int [I

Two-dimensional array of Strings [[Ljava.lang.String;

Part I. Oracle Commerce

Platform REST MVC Web ServicesThe REST MVC Web Services API was designed to address limitations with the Legacy REST API. The REST MVC framework

leverages existing droplets, form handlers and components, creating an API that can be extended easily. You can build REST

services in a modular format by combining model producers. URLs are explicitly defined in a registry, making access to REST

URLs secure. Using access controllers defined in your applications, you can restrict who or under what conditions REST URLs

can be accessed. All properties that are used in REST calls can be filtered, which reduces the amount of information that must

be transferred.

This section describes the Model View Controller (MVC) architecture and framework in detail, and provides examples of

possible customizations. It contains the following information:

• Installing and Configuring the REST MVC Server (page 69) provides information on installing the REST server using CIM,

and configuring various components, such as debugging and enabling desired services

• The REST MVC Definition Framework (page 71) describes the architecture of the REST MVC API, including the file

definitions and components that make up the framework. This section also has instructions on creating a new REST service

• External REST MVC Service Call Examples (page 115) provides detailed information on existing customer-facing REST

service calls, with examples and component configuration information

• Internal REST MVC Service Call Examples (page 179) provides detailed information on existing internal, or agent-facing

REST service calls. This section is intended for users of Oracle Commerce Service Center to REST services for call center

agents

3 Installing and Configuring the REST MVC Server 69

3 Installing and Configuring the REST

MVC Server

The following section describes the installation and configuration of the REST server.

Installing the REST MVC Module

The REST MVC framework is contained within the REST module. Install the REST MVC module using the Oracle

Commerce Platform Configuration and Installation Manager (CIM). When you run the CIM script, the REST

module will be added to your production and agent server instances. For additional information on installing

Oracle Commerce Platform modules, refer to the Platform Installation and Configuration Guide.

Enabling REST Services

For security reasons, when you install the REST MVC module, none of the REST services are enabled. To enable a

service, you must register the actor-chain in your <ATG11dir>/localconfig/atg/rest/

registry/ActorChainRestRegistry.properties file. Any actor-chain that will be used must be

registered. This includes success and error URL actor-chains. Nested actor-chains that are accessed only through

other actors need not be registered. For detailed information on actor-chains, refer to The REST MVC Definition

Framework (page 71) section.

Note: Oracle Commerce Reference Store registers a number of REST actors during installation. Refer to the

Commerce Reference Store Installation and Configuration Guide.

Note: When you add the actor-chain, you should add it to your /localconfig directory, or to your

customization directory.

To register an actor-chain:

1. Create the ActorChainRestRegistry.properties file in your local directory.

2. Add the actor-chain. The following example adds three actor-chains: the login chain, as well as the Success

and Error URL chains.

//home/localconfig/atg/rest/registry/ActorChainRestRegistry.properties

70 3 Installing and Configuring the REST MVC Server

registeredUrls+=\

/atg/userprofiling/ProfileActor/login,\

/atg/userprofiling/ProfileActor/login-success,\

/atg/userprofiling/ProfileActor/login-error,\

Note that if you enter only the actor, the default actor-chain will be used.

3. Save the file.

Note: If you do not register the actor-chain, when the actor-chain is used in a REST Web Service, an error will

occur.

Using Dynamo Session Confirmation Numbers

When using REST services, you want to prevent the processing of malicious site requests. Oracle Commerce

Platform uses a request parameter _dynSessConf, which contains a session confirmation number, to verify that

a request is legitimate. For further information on session confirmation numbers, and the warnings that occur if

the request is not legitimate, refer to the DAFDropletEventServlet section of the Platform Programming Guide.

For Development Purposes Only: The Dynamo session confirmation numbers are required to ensure that

your REST sessions remain secure. During your development process, you may not want to use these numbers

because session confirmation numbers must be passed in for all form and component actors that set property

values. Should you elect to turn them off for development, you must turn them back on when you put your

code into production. To disable the session confirmation numbers, set the enforceSessionConfirmation

parameter in your local /atg/dynamo/service

/actor/Configuration.properties file to false. For additional information, refer to The Form

Element (page 84) and The Component Element (page 77) sections. For information on getting the

Dynamo session confirmation number, refer to the Getting the Session Confirmation Number (page 116)

section.

4 The REST MVC Definition Framework 71

4 The REST MVC Definition

Framework

REST MVC Web Services allow you to use HTTP requests to work with any Oracle Commerce Platform

application. These services provide you with ways to do things such as protect user logins, send data to forms

using mobile applications, or retrieve data from search results. Multiple controllers generate a model map that

can be filtered, and the output from these controllers is used to generate a JSON or XML response.

The REST MVC API can be extended or customized as needed. The following information describes the

components of the API, and provide examples that may be useful when creating custom elements for your

environment.

Architecture Overview

When you initiate a REST MVC service, you send a URL. This URL must be explicitly defined and registered

with the REST MVC Services. If registered, as outlined in the Enabling REST Services (page 69) section, the URL

references controllers, which are known as actors. Each actor, which is configured using XML definition files,

interfaces with a resource, such as a JSP page, a form handler, a servlet bean, a Nucleus component or another

chain of actors, or actor-chains.

These actors generate a ModelMap, which can be filtered and transformed as necessary. The ModelMap is a map

of maps that is populated by actors. The response that is rendered is based on the content that the ModelMap

has generated. ModelMap instances are created by the ModelMapFactory.

Each time that an actor is invoked, an ActorContext is passed into the actor. An ActorContext, which is

created by an ActorContextFactory, is a map of attributes that are relevant to the context in which an actor is

involved.

REST MVC resolves Nucleus components using the ActorChainService, which uses an XML definition file to

define both the chains of actors to execute, and the order in which they must be executed.

Once all the actors have generated their model data, bean filters are applied to the data. Then the response

generator uses the ModelMap to generate a JSON or XML response.

REST MVC Service Flow Example

To understand how the REST MVC processes work, imagine that a customer would like to add a single item from

a catalog to their shopping cart. When the customer, or client REST service, initiates the REST call, the following

occurs:

72 4 The REST MVC Definition Framework

1. The REST Service uses a URL that begins with /rest/model and has been registered with the

ActorChainRestRegistry service. In this example, the URL is:

/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder

This URL contains not only the CartModifierActor Nucleus component, but the addItemToOrder actor-

chain.

The REST Service also verifies the user’s access using the AccessControllerService.

2. The REST Service initializes the actor context from the REST control parameters and the URL. The actor-

context is then passed to the ActorChainService. Because the addItemToOrder actor-chain calls /atg/

commerce/order/purchase/

CartModifierFormHandler, a formActor is invoked. The /atg/commerce/order/ShoppingCart

component is invoked by the componentActor. Refer to the XML Definition Elements (page 73) section

for information on actors and actor-chains.

3. Once all of the actors have provided the data, the ModelMap is filtered with BeanFilters initiated by the

BeanFilteringService. This process modifies the data in the ModelMap. Refer to Bean Filtering (page

101) for additional information.

4. After the filters have been applied to the ModelMap, the ResponseGenerator transforms the ModelMap into

the response, which is configured to be a JSON or XML response. The response is then sent back to the client.

Refer to the Configuring REST MVC Output (page 109) for information on configuring default response

formats.

The following diagram shows the flow of the REST MVC Service call:

Actor Types

The REST MVC API’s modular and extensible functionality is based on actors, which uses a number of different

types of actors to perform a variety of functions. The atg.service.actor.Actor interface contains the

4 The REST MVC Definition Framework 73

following actor types that perform specific actions or provide configurations. For detailed information on any of

these classes, refer to the ATG Platform API Reference.

• Component Actor – Use this actor to set component property values or invoke methods on a component, or

to read component property values

• Droplet Actor – Use this actor when you want to invoke droplets and output data from the droplet to the

ModelMap. Inputs are mapped to the droplet input parameter. Other types of actors can be nested in the

oparam parameter of a DropletActor

• Form Actor – Use this actor to set up form handler inputs and submit a form

• JSP Actor – This actor invokes a JSP page and adds the JSP response or JSP-defined variables to the ModelMap

• Nested Actor – These actors allow you to invoke actor-chains from within other actor-chains, helping to define

modular units of work that can be combined and extended

• Variable Actor – The VarActor enables you to set variables in the actor context

Request URLs

Oracle Commerce Platform REST MVC requests use a /rest/model URL to process requests against the actor

framework. The general format for a REST MVC URL is:

http://host:port/rest/model/actor_chain_component/tail

The format variables are:

• host – The name of the REST server

• port – (Optional) The port from which users access the REST services

• actor_chain_component – The Nucleus path for a Nucleus component that implements the actor-chain

interface

• tail – (Optional) Any attribute that can be processed by a URIProcessor. For actors, the tail is usually the

chain-id. If the tail is omitted, the default actor-chain defined for the actor_chain_component is used.

A typical request may be similar to the following call that adds an item to a shopping cart:

http://rest.example.com:8280/rest/model/atg/commerce/order/purchase/ CartModifierActor/addItemtoOrder

Refer to the External REST MVC Service Call Examples (page 115) and Internal REST MVC Service Call

Examples (page 179) sections to see examples of request URLs in cURL.

XML Definition Elements

The ActorChain.xsd XML schema defines the data structures used within the REST MVC API. The schema

defines XML files that contain actor-template definitions that, in turn, point to Nucleus components. Each of

the components within the schema identifies and performs a specific action and generates a ModelMap.

74 4 The REST MVC Definition Framework

The schema contains the following objects:

REST XML Schema Diagram

The Actor-Template Element

The actor-template, which is the root element of all actor elements, contains one or more actor-chain

elements. This element uses the default-chain-id attribute, which is the default chain that will be executed if

there is no chain-id found in the request. If no default-chain is defined the first chain is executed.

The following is an example of an actor-template that contains a single actor-chain:

4 The REST MVC Definition Framework 75

<actor-template default-chain-id="MyFirstChain"> <actor-chain id="MyFirstChain" transaction="TX_SUPPORTS"> <actor id="order" name="/atg/commerce/ShoppingCartActor" chain-id="summary" return-model-var="orderSummary"> <output id="orderSummary" add-map-children="true" value="${orderSummary}"/> </actor> </actor-chain></actor-template>

The Actor-Chain Element

The second element defined in the schema is the actor-chain, which identifies a series of actors to execute. The

actor-chain can contain one or more actors that include input and/or output elements.

An actor-chain contains the following:

Attribute/Elements Description

id Required. Defines the chain-id. This attribute is used during the XML combination

process, and identifies the chain to execute.

transaction Provides transaction demarcation for the chain. For information on the supported

transaction demarcation types, refer to the Repository Guide. The default value is

TX_SUPPORTS.

Note: If you are creating REST MVC Service calls it is important to note that Profile

and Order-related form handlers require that the transaction be TX_SUPPORTS and

not TX_REQUIRED, as the transaction must be initiated in the form handler and not

be defined prior.

actors An actor-chain can have one or more actors that include input and/or output

elements.

You can use the Dynamo Server Admin to review actors, actor-chains and their attributes.

The Actor Element

When necessary, an actor-chain can invoke a child actor-chain. The actor element passes information from that

parent actor to a child actor, and executes the child actor-chain. Note that you must explicitly define the values

that will be passed from the parent to the child actor-chain.

Actor elements contain the following:

Attribute/Element Description

id Required. The actor ID. This attribute is used for actor ordering.

76 4 The REST MVC Definition Framework

Attribute/Element Description

name Required. The Nucleus path of the actor component to invoke.

return-model-var Provides the variable name of the child actor-chain returned by the ModelMap. The

ModelMap that is returned from the child actor-chain can be accessed using this

variable name.

chain-id The chain ID of the actor component to be executed. If the chain-id is not

specified, the default chain will be executed.

depends This element defines actors that must be executed prior to the execution of the

current actor. There can be multiple depends elements associated with an actor.

depends-if-

present

This element defines actors that, if present, must be executed prior to the execution

of the current actor. There can be multiple depends-if-present elements

associated with an actor.

input This element defines each actor’s input. Actors can have multiple input elements.

output This element defines each actor’s output. Output elements create a map entry in a

ModelMap. Actors can have multiple output elements.

The ActorContext and ModelMap of the parent actor are not passed to the child actor. The following example

shows how information can be passed from a child actor-chain to a parent actor-chain. Note that request

parameters do not need to be passed in explicitly as inputs; you can pass in their variables:

<! – Call another actor-chain to get quantity -><actor id="addItem" name="/atg/commerce/gifts/NewListActor" return-model-var="addItemVar"> <input name="quantity" value="${quantity}"/> <output name="quantity" value="${addItemVar}"/ ></actor>

In the above example, the parent actor-chain contains a quantity ModelMap entry. Map entries are based upon

the child actor-chain. For information on working with implicit objects, which can be used in any chain, refer to

the Working with Implicit Objects (page 99) section.

To pass the entire child ModelMap back to the parent and not have it nested under another variable name,

use the add-map-children="true" in the output element to copy the child ModelMap keys to the parent

ModelMap.

<! – Call another actor-chain to get quantity -><actor id="addItem" name="/atg/commerce/gifts/NewListActor" return-model-var="addItemVar"> <input name="quantity" value="${quantity}"/> <output id="quantity" add-map-children="true" value="${addItemVar}"/ ></actor>

4 The REST MVC Definition Framework 77

The Component Element

The component element executes a method within a component, or sets properties and outputs values from a

component to the output ModelMap.

The component element contains the following:

Attribute/Element Description

name Required. Identifies the Nucleus path of the component.

id Required. This attribute defines the actor ID, and is used for actor ordering.

method Identifies the name of the method to be executed. Use only when invoking a

method.

component-var Provides a variable name that accesses the component’s properties.

method-return-var Identifies the variable name that accesses the method invocation’s returned

value.

set-property-

requires-session-

confirmation

By default, all set-property values require session confirmation numbers. This

property is set to true by default.

invoke-method-

requires-session-

confirmation

By default, all method calls require session confirmation numbers. This property

is set to true by default.

depends This element defines actors that must be executed prior to the execution of the

current actor. There can be multiple depends elements associated with an actor.

depends-if-present This element defines actors that, if present, must be executed prior to the

execution of the current actor. There can be multiple depends-if-present

elements associated with an actor

input This element defines each actor’s input. Actors can have multiple input

elements.

output This element defines each actor’s output. Output elements create a map entry

in a ModelMap. Actors can have multiple output elements.

Example: Resolving a Component

The following example resolves a component that sends output from the properties of the component to

a ModelMap. In this example, the component class instance is saved in the shoppingCart variable of the

ActorContext.

<component id="shoppingCart" name="/atg/commerce/ShoppingCart" component-var="shoppingCart" > <output name=orderId" name="orderId" value="${shoppingCart.last.id}"/ >

78 4 The REST MVC Definition Framework

</component>

Note that you can reference a component without having to invoke a component actor. The following example

shows how you would resolve the orderID component in-line. This works for components that are referenced

only once; if you plan to reference the same component multiple times, it is best to define the variable, as in the

above example:

<input name="ordered" value="${nucleus['/atg/userprofiling/ ActiveCustomerProfile'].orderId}"/>

Example: Executing a Method

You can also use the component element to execute a method on a Nucleus component. The following example

shows how the return value is stored in the orderStatus variable and stores the method return value into the

ModelMap under the orderStatus key.

<component id="orderStatus" name="/atg/commerce/order/OrderServices" method="getOrderStatus" component-var="orderService" method-return-var="orderStatus"> <input name="viewOrderId" value="${param.orderId}" /> <output name="orderStatus" value="${orderStatus}" /></component>

Example: Finding a Method using a String Array

You can also use the component element to find a method by providing a string array. For example, to find a

method that contains a string array, such as atg.commerce.order.OrderLookupService.

getOrderCount(String,String[]), you must provide the String and String[] class-names. In the

following example, the String[] is passed in as [Ljava.lang.String; and passed to the getOrderCount

method.

<component id="orderLookupService" name="/atg/commerce/order/OrderLookupService" method="getOrderCount" method-return-var="numberOfOrders"> <input name="profile" class-name="java.lang.String" value="${profile.repositoryId}" /> <input name="closedStates" class-name="[Ljava.lang.String;" value="$nucleus['/atg/commerce/order/OrderLookup'].closedStates" /></component>

Example: Finding a Method Using an Interface

You can use the component element to find a method if the method has an interface signature. For example, the

atg.commerce.pricing.PricingTools.priceOrderSubtotal(Order, Locale,

RepositoryItem, Map) method needs the interface class-names:

<component id="pricingTools" name="/atg/commerce/pricing/PricingTools" method="priceOrderSubtotal"> <input name="order" class-name="atg.commerce.order.Order" index="0" value="${nucleus['/atg/commerce/ShoppingCart'].current}"/> <input name="locale" class-name="java.util.Locale" index="1" value="${nucleus['/atg/dynamo/servlet/RequestLocale'].locale}"/> <input name="profile" class-name="atg.repository.RepositoryItem" index="2"

4 The REST MVC Definition Framework 79

value="${nucleus['/atg/userprofiling/Profile']}"/> <input name="parameters" class-name="java.util.Map" index="3" value="${null}"/></component>

Example: Finding a Method using Generics

If you are using a method that contains a generic class or interface, use the component element to provide the

necessary type parameters. For example, to find the atg.multisite.SiteGroupManager.

filterInactiveSites (Collection<Site>) method, you would create the following:

<component id="siteGroupManager" name="/atg/multisite/SiteGroupManager" method="filterInactiveSites" component-var="siteGroupManager " method-return-var="sites"> <input name="sites" class-name="java.util.Collection" value="${objectParam.sites}" /> <output id="sites" name="sites" value="${sites}" /></component>

Example: Using Primitives When Executing Methods

The REST MVC framework accepts the use of primitive data types. The following example shows how a boolean

primitive data type is identified using a primitive type name in class-name:

<component id="siteManager" name="/atg/multisite/SiteManager" method="getSitesByState" component-var="siteManager" method-return-var="sites"> <input name="active" class-name="boolean" value="${param.active}" /> <output id="sites" name="sites" value="${sites}" /></component>

Example: Using Primitive Arrays When Executing Methods

You can use an array of primitive data types to return method information. The following example shows how a

Boolean primitive array is used:

<component id="myComponent" name="/custom/MyComponent" method="getOrders" component-var="myComponent" method-return-var="orders"> <input name="flags" class-name="[Z" value="${objectParam.flags}" /> <output id="orders" name="orders" value="${orders}" /></component>

Note that the following class-name values are used to identify primitive array types:

Primitive Data Array Type Class-Name Value

char [C For example, class-name="[C"

short [S For example, class-name="[S"

double [D For example, class-name="[D"

long [J For example, class-name="[J"

80 4 The REST MVC Definition Framework

Primitive Data Array Type Class-Name Value

boolean [Z For example, class-name="[Z"

byte [B For example, class-name="[B"

float [F For example, class-name="[F"

int [I For example, class-name="[I"

Example: Passing Multiple Arguments

To pass more than one argument into a method, you must specify the index attribute on the inputs so that

the input arguments for the method are ordered. For complex object types, you may need to convert the string

value to an object by specifying a PropertyEditor or TagConverter. Any registered property manager can

be used to convert inputs into complex object types so that they may pass method parameters. The system

attempts to coerce the input value to the correct type of object based on the method’s expected input type.

If the method is overloaded, you may need to specify the PropertyEditor to disambiguate between the

overloaded methods. Also, it is usually necessary to define a PropertyEditor for collections of complex

objects since the type of objects contained in the collection cannot be determined at run time.

<component id="methodEx" name="/my/component/Example" method="doSomething" component-var="example" method-return-var="rtn"> <!-Fictitious DateListPropertyEditor that converts pDateRange into a list of dates --> <input name="pDateRange" value="${param.dateRange}" index="0" property-editor="atg.nucleus.PropertyEditors.DateListPropertyEditor"/> <!-We do not need to specify the ProperyEditor but we could specify atg.nucleus.PropertyEditors.LocalePropertyEditor --> <input name="pLocale" value="${param.locale}" index="1"/></component>

Example: Setting Property Values

The following is an example of setting property values on a Nucleus component. The ComponentActor sets the

listId property value and outputs the currentList property value:

<actor-chain-id=getCommerceIdentifierPaymentInfos"> <component id="paymentGroupFormHandler" name="/atg/commerce/order/pruchase/PaymentGroupFormHandler component-var="paymentGroupFormHandler"> <input name="listId" value="${param.listId}" priority="1000" /> <output id="currentList" name="currentList" value="${paymentGroupFormHandler.currentList}" /> </component></actor-chain>

Example: Disabling Component Actor Dynamo Session Confirmation Numbers

Important: The following information is for use within development environments only. Dynamo session

confirmation numbers provide session security and must be enabled in production environments.

4 The REST MVC Definition Framework 81

By default ComponentActors use Dynamo session confirmation numbers, _dynSessConf, for method calls and

setting property values. However, session confirmation numbers are not required for calls such as outputting

properties of a component, a JSPActor or a DropletActor. For detailed information on Dynamo Session

Confirmation Numbers, refer to the Platform Programming Guide.

The following example shows how to disable session confirmation numbers for method calls:

<component id="orderStatus" name="/atg/commerce/order/OrderServices" method="getOrderStatus" component-var="orderService" method-return-var="orderStatus" invoke-method-requires-session-confirmation="false"> <input name="viewOrderId" value="${param.orderId}" class-name="java.lang.String" /> <output id="orderStatus" name="orderStatus" value="${orderStatus.state}" /></component>

The following example shows how to disable set property values:

<component id="salesChannel" name="/atg/commerce/order/OrderServices" component-var="orderService" set-property-requires-session-confirmation="false"> <input name="viewOrderId" value="contactCenter" class-name="java.lang.String" /> <output id="orderStatus" name="salesChannel" value="${orderService.salesChannel} " /></component>

Note that the /atg/dynamo/service/actor/Configuration.enforceSessionConfirmation flag can be

used to disable this requirement during development. It is recommended that this flag is disabled only in your

development environment.

The Droplet Element

The droplet element provides meta-data for Oracle Commerce Platform servlet beans. The DropletActor

executes the servlet beans and adds object values to the ModelMap based on the meta-data.

The droplet element contains the following:

Attribute/Element Description

name Required. This is the Nucleus path of the Oracle Commerce Platform servlet bean.

id Required. This attribute defines the actor ID, and is used for actor ordering.

var Exposes the current frame of the Dynamo param stack as an attribute.

oparam Droplets may have one-to-many oparams.

depends This element defines actors that must be executed prior to the execution of the

current actor. There can be multiple depends elements associated with an actor.

82 4 The REST MVC Definition Framework

Attribute/Element Description

depends-if-

present

This element defines actors that, if present, must be executed prior to the execution

of the current actor. There can be multiple depends-if-present elements

associated with an actor.

input This element defines each actor’s input. Actors can have multiple input elements.

output This element defines each actor’s output. output elements create a map entry in a

ModelMap. Actors can have multiple output elements.

DropletActors can be nested with all types of actors using the oparam element.

The Oparam Element

The oparam element can be used within the droplet element to identify names of droplet oparams. This

element contains the following:

Attribute/Element Description

name Required. The name of the oparam.

actors The oparam element can have one or more actors that include output or set-var

elements.

The following is an example of how to access droplet properties:

<component id="orderLookupBean" name="/atg/commerce/order/OrderLookup" component-var="orderLookupBean" /> <droplet id="switch" name="/atg/dynamo/droplet/Switch"> <input name="value" value="${orderLookupBean.enableSecurity}" /> <oparam name="true"> <droplet id="orderLookup" name="/atg/commerce/order/OrderLookup" var="orderLookupParamStack">... </droplet> </droplet>

The following is an example of a droplet and oparam element:

<!-atg.service.actor.DropletActor will process this tag.--><droplet id="productLookupDroplet" name="/atg/commerce/catalog/ProductLookup" var="productLookupDropletParamStack"> <input name="productId" value="${param.productId}"/> <oparam name="output"> <output name="product" value="${productLookupDropletParamStack.element}" filter-id="orderSummary"/> </oparam> <oparam name="empty">

4 The REST MVC Definition Framework 83

<!-handle case where product is not found --> </oparam></droplet>

Example: Nesting Droplet Elements

It is possible to nest droplet elements. For example:

<actor-chain> <droplet path="/atg/store/droplet/StoreLookupDroplet" var="storeLookup"> <oparam name="output"> <droplet path="/atg/store/droplet/StoreSiteFilterDroplet" var="storeSiteFilter"> <!-read 'items' from StoreLookupDroplet --> <input name="collection" value="${storeLookup.items}"/> <!-output array of stores for the current site --> <oparam name="output"> <output name="stores" value="${storeSiteFilter.filteredCollections}"/> </oparam> </droplet> </oparam> </droplet></actor-chain>

Because each actor-chain has its own ActorContext and ModelMap, you can use the input and output of

nested actors to pass inputs into a nested ActorContext and return outputs from nested ModelMaps. In the

following example, the add-map-children attribute copies the properties in the nested ModelMap to the outer

ModelMap:

</actor-chain><actor-chain id="addItemToOrder-success"> <actor id="order" name="/atg/commerce/ShoppingCartActor" chain=id="detailed" return-model-var="model"> <output id="model" add-map-children="true" value="${model}"/> </actor></actor-chain>

Note that you should make your actors accessible from either the client, using the request parameter, or from

the nested actor, using the variable. Clients pass actors as param, for example param.orderId. Nested actors

pass their variables as ActorContext variables. You must configure your input to look for both param and

ActorContex variables. For example:

<input name="orderId" value="${orderId == null ? param.orderId : orderId}"/>

Example: Evaluating Servlet Beans

When working in a JSP page, you can identify a bean parameter. For example:

<dsp:importbean bean="/atg/svc/agent/ui/formhandlers/CustomerSearchTreeQueryFormHandler" scope="request" /><dsp:droplet name="/atg/droplet/Switch"> <param name="value" bean="CustomerSearchTreeQueryFormHandler.pagesAvailable"/>

84 4 The REST MVC Definition Framework

<oparam name="0"> <!-perform an action --> </oparam></dsp:droplet>

There is no bean attribute available for DropletActors. Instead, you can retrieve servlet beans using the

$nucleus syntax. For example:

<droplet name="/atg/droplet/Switch"> <input name="value" value="${nucleus[/atg/svc/agent/ui/formhandlers/ CustomerSearchTreeQueryFormHandler].pagesAvailable}"/> <oparam name="0"> <!-perform an action --> </oparam></dsp:droplet>

Example: Setting a Variable Within an oparam

The set-var element sets a variable as an attribute. For additional information on this element, refer to The Set

Variable Element (page 96) section. This example shows how to set a set a variable named sites within an

oparam element:

<droplet id="sharingSites" name="/atg/dynamo/droplet/multisite/SharingSitesDroplet" var="sharingSitesParamStack"> <oparam name="output"> <set-var name="sites" value="${sharingSitesParamStack.sites}"/> </oparam></droplet>

You could then use the variable in the following way:

<droplet id="productLookup" name="/atg/commerce/catalog/ProductLookup" var="productLookupParamStack"> <input name="sites" value="${sites}"/> <oparam name="output"> </oparam></droplet>

The Form Element

The form element provides meta-data that the FormActor uses when it executes form handlers and sends

output data to the ModelMap.

The form element contains the following:

Attribute/Element Description

name Required. This is the Nucleus path of the form handler.

4 The REST MVC Definition Framework 85

Attribute/Element Description

handle Required. The name of the handle method to execute.

id Required. This attribute defines the actor ID, and is used for actor ordering.

var The variable name that can access form handler properties and exceptions.

requires-session-

confirmation

By default, all form handler submissions require session confirmation numbers.

This property is set to true by default.

depends This element defines actors that must be executed prior to the execution of

the current actor. There can be multiple depends elements associated with an

actor.

depends-if-present This element defines actors that, if present, must be executed prior to the

execution of the current actor. There can be multiple depends-if-

present elements associated with an actor.

input This element defines each actor’s input. Actors can have multiple input

elements. Note that all input data uses the xxsFiltering parameter to

prevent XXS attacks. For additional information on xxsFiltering, refer to the

Platform Programming Guide.

output This element defines each actor’s output. Output elements create a map entry

in a ModelMap. Actors can have multiple output elements.

use-forwards By default, most form handler submissions use forwards. It is recommended

that you use forwards instead of redirects. To enable redirects, you must set this

attribute to false.

The following is an example of a form element that adds a single item to an order:

<!-- This chain is used to add a single item to an order --><actor-chain id="addItemToOrder" transaction="TX_SUPPORTS"> <form id="cartModifierFormHandler" name="/atg/commerce/order/purchase/ CartModifierFormHandler" var="cartModifierFormHandler" handle="addItemToOrder"> <input name="catalogRefIds" value="${param.catalogRefIds}"> <tag-converter class-name="atg.droplet.ArrayTagConverter"/> </input> <input name="productId" value="${param.productId}"/> <input name="quantity" value="${param.quantity}"/> <input name="locationId" value="${param.locationId}"/> <input name="siteId" value="${param.siteId}"/> <!-- optional giftlistId/giftlistItemId are set if the item is added from a giftlist --> <input name="giftlistId" value="${param.addToWishlist ? nucleus['/atg/userprofiling/Profile'].wishlist.repositoryId : param.giftlistId}"/> <input name="giftlistItemId" value="${param.giftlistItemId}"/> <input name="addItemToOrderErrorURL" value="/model/atg/commerce/order/ purchase/CartModifierActor/addItemToOrder-error"/> <input name="addItemToOrderSuccessURL" value="/model/atg/commerce/order/

86 4 The REST MVC Definition Framework

purchase/CartModifierActor/addItemToOrder-success"/> </form></actor-chain><actor-chain id="addItemToOrder-error" transaction="TX_SUPPORTS"> <actor id="error" name="/atg/commerce/order/purchase/CartModifierActor" chain-id="error" return-model-var="model"> <output id="model" add-map-children="true" value="${model}"/> </actor></actor-chain><actor-chain id="addItemToOrder-success" transaction="TX_SUPPORTS"></actor-chain><actor-chain id="error" transaction="TX_SUPPORTS"> <component id="fh" name="/atg/commerce/order/purchase/CartModifierFormHandler" component-var="fh"> <output id="formError" name="formError" value="${fh.formError}"/> <output id="formExceptions" name="formExceptions" value="${fh.formExceptions}" filter-id="detailed"/> <!-- Did a concurrent update exception occur? --> <output id="concurrentUpdate" name="concurrentUpdate" value="${fh.concurrentUpdate}"/> <output id="order" name="order" value="${fh.concurrentUpdate ? fh.order : null}" filter-id="detailed"/> </component></actor-chain>

By default, all form elements define success and error chains. You can use XML combining to modify the default

behavior of the chains. The following example shows what you would create to make a combined file that

modifies the addItemToOrder-success chain:

<actor-chain id="addItemToOrder-success"> <actor id="order" name="/atg/commerce/ShoppingCartActor" chain-id="summary" return-model-var="model"> <output id="model" add-map-children="true" value=${model}" /> </actor></actor-chain>

The success or error URL, if present, is generally a REST URL that references another actor that generates the next

page. Success and error URL are specified by the actor definition. Your success and error URLs should start with

/model/atg if you are forwarding. If you are doing a redirect, start your URLs with /rest/model/atg. The

FormActor uses the use-forward attribute. Note that it is better to use forwarding than redirection.

Form Handler Arrays

When using a JSP form, you can set the individual form array elements. For example, if you wanted to review

each user and set their input field to be first name and last name:

<dsp:droplet name="/atg/dynamo/droplet/ForEach"> <dsp:param bean="MultiProfileAddFormHandler.users" name="array"/> <dsp:oparam name="output"> <dsp:input bean="MultiProfileAddFormHandler.users[param:index] firstName" type="text"/> <dsp:input bean="MultiProfileAddFormHandler.users[param:index] lastName" type="text"/> </dsp:oparam></dsp:droplet>

4 The REST MVC Definition Framework 87

When using a FormActor, use the priority attribute to initialize input array size before the array is populated

if you are passing input arrays. For example:

<actor-chain id="addMultipleItemsToOrder" transaction="TX_SUPPORTS"> <form id="cartModifierFormHandler" name="/atg/commerce/order/purchase/CartModifierFormHandler" var="cartModifierFormHandler" handle="addMultipleItemsToOrder"> <input name="addItemCount" value="${param.addItemCount}" priority="1000" /> <input name="items[].catalogRefId" value="${objectParam.items[].catalogRefId}" array-size="${param.addItemCount}"/> <input name="items[].productId" value="${objectParam.items[].productId}" array-size="${param.addItemCount}"/>… </form></actor-chain>

To set individual elements, use the [ ] syntax, and pass in array-size attributes for each input array element.

When a form actor processes an input tag that contains [ ] in the name string, the input is treated as an input

array. Based upon the array-size, the FormActor adds the index between the brackets, for example, [0] or

[Index]. It then adds the form input tag to the form tag. Both the input name and value can use the [ ]

syntax, with the index substituted for their attribute values.

In the following example, the first input tag value uses an array property and the second input tag passes in a

scalar value:

<input name="currentList[].amount" value="${objectParam.cipiList[].amount}" priority="1" array-size="${param.addItemCount}"/>or<input name="currentList[].amount" value="25.00" priority="1" array-size="${param.addItemCount}"/>

Use tag converters to convert array inputs:

<input name="catalogRefIds" value="${param.catalogRefIds}"> <tag-converter class-name="atg.droplet.ArrayTagConverter"/></input>

Example: Disabling Form Actor Dynamo Session Confirmation Numbers

Important: The following information is for use within development environments only. Dynamo session

confirmation numbers provide session security and must be enabled in production environments.

By default, FormActors use Dynamo Session Confirmation Numbers, _dynSessConf, for method calls and

setting property values. However, session confirmation numbers are not required for calls such as outputting

properties of a component, a JSPActor, or a DropletActor. For detailed information on Dynamo Session

Confirmation Numbers, refer to the Platform Programming Guide.

The following example shows how to disable session confirmation numbers for a FormActor:

88 4 The REST MVC Definition Framework

<actor-chain id="login" transaction="TX_SUPPORTS"> <form id="profileFormHandler-login" name="/atg/userprofiling/ProfileFormHandler" handle="login" var="profileFormHandler" requires-session-confirmation="false"> <input name="value.login" value="${param.login}" /> <input name="value.password" value="${param.password}" /> <input name="loginErrorURL" value="/rest/model/atg/userprofiling/ProfileActor/login-error"/> <input name="loginSuccessURL" value="/rest/model/atg/userprofiling/ProfileActor/login-success"/> </form></actor-chain>

Note that the /atg/dynamo/service/actor/Configuration.enforceSessionConfirmation flag can

also be used to disable this requirement during development. Again, it is recommended that this flag is disabled

only in your development environment.

Example: Form Error Handling

When a form handler encounters an error, it typically processes the error by adding a DropletException to

the form handler and forwarding to an error URL. The handle method returns false, indicating that a forward

or redirect has occurred, and the actor-chain immediately terminates. Success or error URLS can be supplied to

the form handler using the input element. If the error URL has been defined to use another actor-chain, a new

ModelMap and ActorContext is created to issue the response.

For example, to invoke the cartModifierActor to pass an error URL that will re-render the Add Item to Order

page if there is an error:

# /atg/commerce/order/purchase/cartModifierActor<actor-template default-chain-id="addItemToOrder"> <actor-chain id="addItemToOrder" transaction="TX_SUPPORTS"> <form id="cartModifierFormHandler" name="/atg/commerce/order/ purchase/CartModifierFormHandler" var="cartModifierFormHandler" handle="addItemToOrder"> <input name="catalogRefIds" value="${param.catalogRefIds}"> <tag-converter class-name="atg.droplet.ArrayTagConverter" /> </input> <input name="productId" value="${param.productId}" /> <input name="quantity" value="${param.quantity}" /> <input name="locationId" value="${param.locationId}" /> <input name="siteId" value="${param.siteId}"/> <input name="addItemToOrderErrorURL" value="/model/atg/commerce/order/ purchase/CartModifierActor/addItemToOrder-error"/> <input name="addItemToOrderSuccessURL" value="/model/atg/commerce/order/ purchase/CartModifierActor/addItemToOrder-success"/> </form> </actor-chain> <actor-chain id="addItemToOrder-error" transaction="TX_SUPPORTS"> <actor id="error" name="/atg/commerce/order/purchase/CartModifierActor" chain-id="error" return-model-var="model"> <output id="model" add-map-children="true" value="${model}" /> </actor> </actor-chain> <actor-chain id="addItemToOrder-success"> <actor id="order" name="/atg/commerce/ShoppingCartActor" chain-id="summary" return-model-var="model"> <output id="model" add-map-children="true" value=${model}" />

4 The REST MVC Definition Framework 89

</actor> </actor-chain>

<actor-chain id="error" transaction="TX_SUPPORTS"> <component id="fh" name="/atg/commerce/order/purchase/CartModifierFormHandler" component-var="fh"> <output id="formError" name="formError" value="${fh.formError}" /> <output id="formExceptions" name="formExceptions" value="${fh.formExceptions}" filter-id="detailed" /> <!-- Did a concurrent update exception occur? --> <output id="concurrentUpdate" name="concurrentUpdate" value="${fh.concurrentUpdate}" /> <output id="order" name="order" value="${fh.concurrentUpdate ? fh.order : null}" filter-id="detailed" /> </component> </actor-chain></actor-template>

If the CartModifierFormHandler encounters an error, the form handler identifies a formError and forwards

to the AddItemToOrderErrorURL property in the CartModifierFormHandler.

If there is no error, the detailed view of the order is displayed.

Error Code Response Types

Note that there are two types of error message patterns provided as a response. For Oracle Commerce Core

Commerce-based form handlers, the error message response is similar to the following:

{ "formError":true, "formExceptions":[{ "localizedMessage":"There was an error updating this order", "cause":null, }], "concurrentUpdate":false}

For Oracle Commerce Platform-based form handlers, the form handler response is similar to the following:

{"formError":true, "formExceptions":[{"localizedMessage":"The password andlogin do not match","errorCode":"invalidPassword"}]}

The JSP Element

The jsp element executes a JSP page and sends output object values to the output ModelMap. JSPActors

typically write to variables that are mapped by the JSPActor definition.

Note that existing JSP templates that were created with the Oracle Commerce Platform Legacy REST framework

can be applied to JSPActors.

Note: If possible, use DropletActors instead of JSPActors, as DropletActors are more modular and do not

require configuring a WAR file.

90 4 The REST MVC Definition Framework

The jsp element contains the following:

Attribute Description

id Required. This attribute defines the actor ID, and is used for actor ordering.

page Required. This is the absolute path of the JSP URL, excluding the context root.

context Required. The context root of the JSP URL.

response-var The value that is written to the HTTP response by the JSP page. You can reference

this attribute in an output element to add the response to the output model. This

is useful for returning HTML snippets to render.

depends This element defines actors that must be executed prior to the execution of the

current actor. There can be multiple depends elements associated with an actor.

depends-if-

present

This element defines actors that, if present, must be executed prior to the execution

of the current actor. There can be multiple depends-if-present elements

associated with an actor.

input This element defines each actor’s input. Actors can have multiple input elements.

output This element defines each actor’s output. Output elements create a map entry in a

ModelMap. Actors can have multiple output elements.

The following is an example of a jsp element:

<actor-chain id="shippingMethods"> <jsp page="/atg/commerce/pricing/shippingMethodsActor.jsp" context="DCS"> <!-if true, getPrices will return prices with the shipping methods --> <input name="getPrices" value="${param.getPrices}"> <output name="shippingMethods" value="${shippingMethods}"/> <output name="currencyCode" value="${currencyCode}"/> </jsp></actor-chain>

The following is an example of the JSP that the element invokes:

<%-- Return available shipping methods, optionally with prices - Optional parameters: getPrices if true, will return prices with the shipping methods - Model output: shippingMethods currencyCode --%><dsp:page> <dsp:importbean bean="/atg/commerce/pricing/AvailableShippingMethods" /> <dsp:importbean bean="/atg/commerce/pricing/CurrencyCodeDroplet" />

4 The REST MVC Definition Framework 91

<dsp:importbean bean="/atg/commerce/order/purchase/ShippingGroupFormHandler" /> <dsp:importbean bean="/atg/commerce/ShoppingCart" /> <dsp:importbean bean="/atg/userprofiling/Profile" />

<dsp:getvalueof var="shippingMethodsMap" class="java.core.util.HashMap" scope="request"/> <dsp:getvalueof var="shippingGroup" bean="ShippingGroupFormHandler .firstNonGiftHardgoodShippingGroupWithRels" /> <dsp:getvalueof var="getPrices" param="${param.getPrices}" /> <dsp:droplet name="AvailableShippingMethods"> <dsp:param name="shippingGroup" value="${shippingGroup}" /> <dsp:oparam name="output"> <dsp:getvalueof var="availableShippingMethods" vartype="java.lang.Object" param="availableShippingMethods" /> <c:forEach var="availableShippingMethod" items="${availableShippingMethods}"> <c:set var="shippingPrice" value="null" /> <c:if test="${getPrices == 'true'}"> <%-Determine shipping price for the current shipping method --%> <dsp:droplet name="/atg/store/pricing/PriceShippingMethod" var="priceShippingMethod"> <dsp:param name="shippingMethod" value="${availableShippingMethod}" /> <dsp:oparam name="output"> <c:set target="${shippingMethodsMap}" property="${availableShippingMethod}" value="${priceShippingMethod.shippingPrice}" /> </dsp:oparam> </dsp:droplet> </c:if> </c:forEach> </dsp:oparam> <!-Sets property in the ActorContext --> <c:set name="shippingMethods" value="${shippingMethodsMap}" scope="request" /> </dsp:droplet>

<%-Add the currencyCode if returning prices --%> <c:if test="${getPrices == 'true'}"> <dsp:getvalueof var="priceListLocale" vartype="java.lang.String" bean="Profile.priceList.locale" /> <dsp:droplet name="CurrencyCodeDroplet" var="currencyCodeDroplet"> <dsp:param name="locale" value="${priceListLocale}" /> <dsp:oparam name="output"> <!-Sets property in the ActorContext --> <c:set name="currencyCode" value="${currencyCodeDroplet.currencyCode}" scope="request" /> </dsp:oparam> </dsp:droplet> </c:if></dsp:page>

Example: HTML Output

JSPActors can output HTML snippets to pass to the client using the response-var property. For example:

<jsp id="popup" page="/myapp/mypopup.jsp" context="myapp" response-var="popupVar"> <output id="popup" name="popup" value="${popupVar}"/></jsp>

92 4 The REST MVC Definition Framework

Example: Migrating Previous REST JSP Templates

To apply Oracle Commerce Platform Legacy REST JSP templates to the JSPActors:

<jsp id="displayCart" page="/orderDetail.jsp" context="mobile" response-var="orderJSON" > <output id="orderOut" name="order" value="${orderJSON}" embed-for-mime-type="application/json"/></jsp>

The Output Element

The output element defines a map entry in a ModelMap. Once the actors are executed, the output values are

evaluated and added to the ModelMap based on the name attribute.

The output element contains the following:

Attribute/Element Description

id Required. This attribute defines the actor ID, and is used for actor ordering.

name Defines the name of the map entry. The value of this attribute can be static, or a

dynamic EL expression. For additional information on ActorContext variables,

refer to the Working with Implicit Objects (page 99) section.

value Defines the value of the map entry. The value of this attribute can be static, or a

dynamic EL expression. For additional information on ActorContext variables,

refer to the Working with Implicit Objects (page 99) section.

filter-id Defines the bean filter that will be applied when the value object is filtered

using the BeanFilterService. Note that the filter-id attribute on a bean

filter property will override this filter-id attribute.

embed-for-mime-type Identifies if the value of the object should be embedded within the server

response. For example, if the object is a JSON string, and it should be embedded

in the JSON response, set the embedded mime attribute to application/

json. If the ResponseGenerator has been set to output as JSON, the string

is added to the JSON response. If the EmbeddedMimeType does not match the

response mime type, (for example, the response mime type is set to XML), the

JSON response will be encoded as a string inside the XML response.

add-map-children This attribute, when set to true, copies the key/value pairs of a map value into

the ModelMap. The value must be a map. This attribute is often used to pass the

values of a child ModelMap to a parent ModelMap in a nested actor call.

depends This element defines actors that must be executed prior to the execution of the

current actor. There can be multiple depends elements associated with an actor.

depends-if-present This element defines actors that, if present, must be executed prior to the

execution of the current actor. There can be multiple depends-if-present

elements associated with an actor.

4 The REST MVC Definition Framework 93

Attribute/Element Description

message The output tag supports internationalized messages that are added to the

ModelMap.

The following is an example of an output element:

<output name="globalInfo" value="${CSREnvironmentTools}" filter-id="globalTemplate"/>

The filter-id identifies the filter for the BeanFilterService to apply. Refer to the Bean Filtering (page

101) section for further information.

The output tag supports localized message tags, which add internationalized messages to the ModelMap. By

default, all messages are localized based upon the current user’s locale, however, the locale can be passed in

using the message tag.

The message element contains the following:

Attribute/Element Description

id Required. This attribute defines the message ID.

locale-code The locale that will be used to localize the message, for example, en_US. If not

available, the system will use the ServletUtil.userLocale setting.

bundle Identifies the resource bundle that contains the resource key.

key The resource key identified by the resource bundle.

message-param If message parameters are required during the resource lookup, you can use the

attributes used by this element:

id – The ID of the message param.

value – The value to pass.

The following is an example of an output element with a message element. Messages are, by default, localized

using the user’s locale, however, you can set the locale using the message tag:

<output id="error" name="error" <message id="PRODUCT_NOT_IN_CURRENT_CATALOG" bundle="atg.commerce.catalog.custom.UserResources key="PRODUCT_NOT_IN_CURRENT_CATALOG"> <message-param id="arg0" value="${(productId != null) ? productId : param.productId}"/> </message></output>

The output from the example above would be:

94 4 The REST MVC Definition Framework

{"error": {"messageCode" : "PRODUCT_NOT_IN_CURRENT_CATALOG","localizedMessage" : "Product xprod2099 is not defined in the current catalog"}}

The Input Element

The input element defines actor inputs and is used to pass values to the actors. The input element is used for

all actor types.

The input element contains the following:

Attribute/Element Description

name Required. Defines the name of the input element.

value Defines the value of the input element.

property-editor In certain actors, a property editor is used to modify the JSON or XML value into

a complex object. Refer to The Component Element (page 77) section for

information on working with property editors.

tag-converter Use this element to coerce the JSON or XML value into a complex object using the

class-name attribute.

priority This attribute determines the order of the actor inputs.

array-size Used only by the FormActor, this attribute is used to support form handler

array support. Refer to The Form Element (page 84) section for additional

information.

index Used only by the ComponentActor in a method call, this attribute defines the

order of the method’s parameters. Refer to The Component Element (page 77)

section for additional information on this attribute.

The input element uses the xxsFiltering parameter to filter all input data. By default, this parameter is set

to true. For additional information on xxsFiltering, refer to the Filtering Requests to Prevent Cross-Site Attacks

section in the Platform Programming Guide.

The following is an example of an input element:

<input name="viewOrderId" value="${param.OrderId}" class-name="java.lang.String" index="0"/>

The Depends and Depends-If-Present Element

The depends element defines actors that must be executed before another actor can run. If the actor that must

be run first cannot be found, an error will occur, but the current actor will still execute. This element allows you

4 The REST MVC Definition Framework 95

to order actors in an actor-chain when the actors have been XML combined. If you do not specify a depends

attribute, actors will be executed in the order in which they appear in the definition file.

The depends-if-present element is similar to the depends element, in that it specifies an actor that must run

prior to the current actor’s execution. However, in the depends-if-present element, the specified actor is not

required in the actor-chain. This element is best used when an actor in the actor-chain may not be available. The

element allows you to identify actor order, but will not generate an error if the requirements are not met.

Both the depends and the depends-if-present elements use the required id attribute, which identifies the

ID of the actor that must run before the current actor.

Ordering Actors

The depends and the depends-if-present elements control actor-chain ordering. If your actors are defined

in a single file, the order in which you define your actors is the way they will be executed. However, if you

have actors that you have defined in various overriding layers and you want to change their order, you must

identify the order using the depends and depends-if-present elements. If actor order is not important, these

elements are not required in the actor definition. For example, if you have a base configuration file for shipping

groups:

<actor-template> <droplet id="ApplicableShippingGroups" name="/atg/commerce/custsvc/ order/ApplicableShippingGroups" var="applicableShippingGroups"> <!-- The ShippingGroupDroplet must be initialized before the ApplicableShippingGroups droplet can be invoked --> <input name="order" value="${nucleus["/atg/commerce/custsvc/environment/ CSREnvironmentTools"].currentOrder}"/> <oparam name="output"> <output name="shippingAddresses" value="${applicableShippingGroups. shippingGroups}" filter-id="shippingAddress"/> </oparam> </droplet> </actor-chain><actor-template>

The file that you would create in your local configuration directory to order actors would contain:

<actor-template> <actor-chain id="shippingAddresses" transaction="TX_SUPPORTS"> <droplet id="ShippingGroupDroplet" name="/atg/commerce/custsvc/order/ShippingGroupDroplet"> <input name="clear" value="${param.init}"/> <input name="initShippingGroups" value="${param.init}"/> <input name="initShippingInfos" value="${param.init}"/> <input name="initBasedOnOrder" value="${param.init}"/> <input name="shippingGroupTypes" value="${nucleus\["/atg/commerce/custsvc/util/CSRConfigurator"\]. shippingGroupTypesToBeInitialized"/> </droplet> <droplet id="ApplicableShippingGroups"> <!-The ShippingGroupDroplet must be initialized before the ApplicableShippingGroups droplet can be invoked --> <depends id="ShippingGroupDroplet"/> </droplet> </actor-chain><actor-template>

96 4 The REST MVC Definition Framework

In this example, the ShippingGroupDroplet initializes the shipping group information. However, because

it must be invoked before running the ApplicableShippingGroups droplet, you must define a depends

element, indicating that the ShippingGroupDroplet should be executed first.

The Set Variable Element

The set-var element sets a variable as an attribute in the actor context within the scope of the actor-chain. This

element can be used only within the input, output, or oparam elements.

This element contains the following:

Attribute/Element Description

id Required. The actor ID. This attribute is used for actor ordering.

name Required. The name of the map entry. This can be a static or dynamic EL

expression.

value This attribute defines the value of the map entry, and can be a static or dynamic

EL expression.

depends This element defines actors that must be executed prior to the execution of the

current actor. There can be multiple depends elements associated with an actor.

depends-if-present This element defines actors that, if present, must be executed prior to the

execution of the current actor. There can be multiple depends-if-present

elements associated with an actor.

The following is an example of the set-var element:

<component id="fh" name="/atg/agent/userprofiling/EnvironmentLogoutFormHandler" component-var="fh"> <output id="allWarnings" name="allWarnings" value="${environmentChangeState.allWarnings}"> <set-var name="environmentChangeState" value="${fh.environmentChangeState}" /> </output> <output id="isActiveTicketDisposition" name="activeTicketDisposition" value="${environmentChangeState.processActiveTicketDisposition}" /></component>

In this example, the set-var element sets the environmentChangeState variable in the actor context while

executing the first output.

Actor XML Definition File Examples

This section provides a few actor definition examples. Note that to create an ActorChainService component,

you must create both a Nucleus component and an XML file that contains the actor-template instance

definition. Note that when working with actor definitions, it is best to use XML combination to add your

customizations.

4 The REST MVC Definition Framework 97

Example: Creating a Order Confirmation Actor

The following is an example that creates a ComponentActor that adds a component to the ModelMap. This

actor will reference a Nucleus component and an XML file that defines the actor-template.

1. Define the OrderConfirmation component to call the ActorChainService, and then set the

definitionFile property value to the appropriate XML file:

/custom/atg/commerce/order/purchase/OrderConfirmation.properties

$class=atg.service.actor.ActorChainService

definitionFiles+=/custom/atg/commerce/orderConfirmationActor.xml

2. Create a orderConfirmationActor XML file that contains the following, where the actor-chain defines a

ComponentActor:

/custom/atg/commerce/order/purchase/orderConfirmation.xml

<actor-template>

<actor-chain id="orderConfirmation" transaction="TX_SUPPORTS">

<!-atg.service.actor.ComponentActor processes this tag. -->

<!-this tag adds the component to the model map -->

<component id="shoppingCart" name="/atg/commerce/ShoppingCart"

component-var="shoppingCart">

<output name="orderId" value="${shoppingCart.last.id}"/>

</component>

</actor-chain>

</actor-template>

Example: Creating a Shipping Address Actor

The following is an example that creates a Nucleus component and an XML file that defines an actor-

template instance that allows you to access shipping address data.

1. Define the Nucleus component and identify the XML file that defines the actor-template:

/custom/atg/commerce/ShippingAddressesActor.properties

$class=atg.service.actor.ActorChainService

definitionFiles+=/custom/atg/commerce/shippingAddressesActor.xml

2. Create the XML file that creates a shippingAddresses actor-chain:

/custom/atg/commerce/shippingAddressesActor.xml

<actor-template>

<actor-chain id="shippingAddresses" transaction="SUPPORTS">

<!-atg.service.actor.DropletActor processes this tag.-->

<droplet id="ShippingGroupDroplet"

name="/atg/commerce/custsvc/order/ShippingGroupDroplet">

<!-The droplet input is taken from the query string -->

<!-This tag sets the droplet input parameter -->

<input name="clear" value="${param.init}"/>

<input name="initShippingGroups" value="${param.init}"/>

<input name="initShippingInfos" value="${param.init}"/>

<input name="initBasedOnOrder" value="${param.init}"/>

<input name="shippingGroupTypes" value="${nucleus["/atg/commerce/

custsvc/util/CSRConfigurator"].

shippingGroupTypesToBeInitialized"/>

</droplet>

98 4 The REST MVC Definition Framework

<!-atg.service.actor.DropletActor processes this tag.-->

<droplet id="ApplicableShippingGroups"

name="/atg/commerce/custsvc/order/ApplicableShippingGroups"

var="applicableShippingGroupsParams">

<!-This tag sets the droplet input parameter -->

<input name="order" value="${nucleus["/atg/commerce/custsvc/

environment/CSREnvironmentTools"].currentOrder}"/>

<oparam name="output">

<output name="shippingAddresses"

value="${applicableShippingGroupsParams.shippingAddress}"

filter-id="shippingAddress"/>

</oparam>

</droplet>

</actor-chain>

<actor-template>

Example: Creating a Profile Form Handler Actor

The following example demonstrates how to create an actor-template with multiple chains. This allows you

to define multiple chains in the same XML file. However, it is best to define XML files based on a single functional

area.

This example creates a ProfileActor, which contains XML chains for its functional areas. This actor contains

profile-related functions such as getting, creating, or deleting a profile, profile address, or credit card. It is best

to provide the form handler or any single-service function within an actor, as doing so groups related chains

together and reduces the number of Nucleus components that must be defined.

1. To create this actor, define the Nucleus component:

/custom/atg/userprofiling/ProfileActor.properties

$class=atg.service.actor.ActorChainService

definitionFiles+=/custom/atg/userprofiling/profileActor.xml

2. Create the XML file:

/custom/atg/userprofiling/profileActor.xml

<actor-template default-chain-id="getProfile">

<actor-chain id="createProfile" transaction="TX_SUPPORTS">

...

...

</actor-chain>

<actor-chain id="updateProfile" transaction="TX_SUPPORTS">

...

</actor-chain>

<actor-chain id="getProfile" transaction="TX_SUPPORTS">

...

</actor-chain>

<actor-chain id="deleteProfile" transaction="TX_SUPPORTS">

...

</actor-chain>

<actor-chain id="createAddress" transaction="TX_SUPPORTS">

...

</actor-chain>

<actor-chain id="createCreditCard" transaction="TX_SUPPORTS">

...

4 The REST MVC Definition Framework 99

</actor-chain>

</actor-template>

Working with Implicit Objects

Although it is best to explicitly define objects, the REST framework supports the ability to work with the

following defined implicit objects:

Object Description

atgActorModel Maps the current actor-chain’s modelMap. This does not reference the parent

chain’s modelMap.

cookie.name Maps a cookie name to a cookie object.

header.name Maps a header name to a single string value.

headerValues.name Maps a header name to an array of string values.

nucleus Maps a Nucleus component.

objectParam.name Maps a request parameter name to an object value.

param.name Maps a request parameter name to a single string value.

paramValues.name Maps a request parameter name to an array of string values.

request This object maps to the current request.

session This object maps to the user’s session.

Accessing Actor Context Variables

Actor context variables and attributes are available only for the duration of the actor-chain. Each nested actor-

chain or child actor-chain is given a new ActorContext and ModelMap, and is unable to reference their parent’s

ActorContext and ModelMap. However, all actor variables are added to the ActorContext as attributes, which

you can access.

To access ActorContext, request or session attributes, you can map the attribute to a value using the

${order.id} syntax or ${commerceItems[0]} array notation.

For example, you could resolve a Nucleus component using the following EL expression:

${nucleus['/atg/commerce/ShoppingCart'].current}

If a variable name does not start one of the implicit objects listed in the Working with Implicit Objects (page

99) section, the system will look up the variable in the attributes of the ActorContext, then in the attributes

of the request and finally in the attributes of the session. Note that you should have a separate actor context per

actor-chain.

100 4 The REST MVC Definition Framework

When working with a JSP page and JSPActors, the JSP c:set tag saves the variable in a request or session

attribute. The attributes that are set using the c:set tag are accessible in the actor definition and can be

referenced in an output element to include in the ModelMap.

Working with Maps

When working with parameters for mapping, use the objectParam.name, param.name or paramValues.name

inputs.

For example, the following actor-chain definition uses the completeQuoteParameters map string keys and

values to obtain quote information using the objectParam object:

<!-- complete quote--><actor-chain id="completeQuote" transaction="TX_SUPPORTS"> <form id="quoteFormHandler" name="/atg/commerce/order/purchase/QuoteFormHandler" handle="completeQuote" var="quoteFormHandler"> <input name="orderId" value="${param.orderId}"/> <input name="completeQuoteParameters" value="${objectParam.completeQuoteParameters}"/> <input name="completeQuoteErrorURL" value="${completeQuoteErrorURL != null ? completeQuoteErrorURL : '/model/atg/commerce/order/purchase/ QuoteActor/quote-error'}"/> <input name="completeQuoteSuccessURL" value="${completeQuoteSuccessURL != null ? completeQuoteSuccessURL : '/model/atg/commerce/order/purchase/ QuoteActor/quote-success'}"/> </form></actor-chain>

The output from this call would be the following, which identifies that the REST class-type is a HashMap:

{ "atg-rest-class-type":\"java.util.HashMap\", "atg-rest-values":{ "agentId": \"agent007\", "providerNote": \"Quote good until 11/11/14\", "externalId": \"external001\", "expirationDate": \"2014-11-11 11:00\", "orderAdjustment": \"5.0\", }}

Combining Actor Definitions

You can use XML combining to customize the elements used in REST. The following attributes are used during

the XML combining. For additional information on XML combining, refer to the Platform Programming Guide.

Element Match Attribute

actor id

actor-chain id

4 The REST MVC Definition Framework 101

Element Match Attribute

component id

depends id

depends-if-present id

droplet id

form id

input name

jsp id

message id

message-param id

oparam name

output id

Bean Filtering

The BeanFilterService filters the properties of a java bean or repository item and converts beans into a map

of properties. The BeanFilterService reads XML definition files that define which properties of a Java class or

repository item should be included in the filtered view of the object. The XML definitions include ways to remap

property names and transform properties.

By default, the BeanFilterService is applied to the ModelMap by the REST MVC framework before

generating a JSON or XML response. However, you can filter objects at any time. For example, you can use the

BeanFilterService as a ComponentActor to filter a repository item before adding it to the ModelMap. This

converts the repository item into a map of primitive objects:

<component name="/atg/dynamo/service/filter/bean/BeanFilterSerivce" method="applyFilter" method-return-var="rtn"> <input name="pTargetObject" value="${myRepositoryItem}" /> <output name="myRepositoryItem" value="{rtn}" /></component>

There are two types of bean filters, those for repository items and those for Java bean classes. By using the

ComponentActor, you can add a component to the ModelMap, which can then be filtered by the class that the

component implements. For example:

<actor-template> <actor-chain> <component id="profile" name="/atg/userprofiling/Profile"

102 4 The REST MVC Definition Framework

component-var="profile"> <output name="profile" value="${profile}" /> </component> </actor-chain></actor-template>

This allows the Profile class to filter the components:

<bean-filtering> <bean type="atg.userprofiling.Profile"> <filter id="default"> <property name="email" /> <property name="lastName" /> <property name="firstName" /> <property name="dataSource" /> <property name="homeAddress.postalCode" target="homeAddress.postalCode" /> <property name="gender" /> <property name="dateOfBirth" /> </filter> </bean></bean-filtering>

Bean filters combine filter definitions from all classes or interfaces for an object using the filter-id property.

You can also include other bean filters within a bean filter by using the include-filter attribute.

It is best to define a filter for every object, so that you can control its output. Note that if an object has no filters

defined, it will output all properties.

The following XML values are defined by the atg/dtds/beanfilter/beanFiltering_1.0.dtd file:

The Bean Element

The bean element defines a filter for a Java bean class or interface that is in the ModelMap. The filter can be

defined at any level of the class and interface hierarchy, and will automatically apply classes and interfaces that

have a filter with the same ID. Note that it is best to insert whole objects into the ModelMap and allow bean

filtering to control the way that the object is viewed. By defining a filter for every object you can control the

output for that object.

The bean element contains the following attributes:

Attribute Description

name The fully qualified package name of the class or interface.

default-filter The ID of the default filter. If no default-filter is defined, the first filter is used.

Available Filters

There are three filters that are primarily used:

4 The REST MVC Definition Framework 103

• detailed – This filter provides a detailed list

• short – This filter provides a short list

• summary – This filter provides a summary

The following is an example of the ElectronicShippingGroup filter:

<bean type="atg.commerce.order.ElectronicShippingGroup> <filter id="summary"> <property name="emailAddress"/> <property name="shippingAddress" hidden="true"/> </filter></bean>

If the same property is defined in the super and sub-class, the sub-type definition overrides the super-type

property definition if both reference the same filter ID. If filters are defined on two interfaces that a Java servlet

bean implements, but no filter is defined on the classes that the bean implements, the output from both

interface filters will be included.

Working with Shared Properties

The bean element allows you to define properties that are shared in one filter and then reference the filter

class by super-type. For example, the ElectronicShippingGroup and the HardgoodShippingGroup are

similar. However, the ElectronicShippingGroup adds the emailAddress property and does not require

the ShippingAddress property. In the following example, the majority of the properties have been moved to

the super-type class ShippingGroup. Because the HardgoodShippingGroup contains all of the properties

of the based ShippinGroup, it does not need a definition. The ElectronicShippingGroup defines the

emailAddress property and hides the unneeded shippingAddress property.

Note: Combining all shipping groups within one filter is not recommended, the following is merely an example.

It is best to have a filter defined for each shipping group:

<bean type="atg.commerce.order.ShippingGroup"> <filter id="summary"> <property name="actualShipDate"/> <property name="id"/> <property name="shipOnDate"/> <property name="shippingAddress"/> <property name="shippingGroupClassType"/> <property name="shippingMethod"/> <property name="specialInstructions"/> <property name="stateAsUserResource"/> <property name="stateDetail"/> <property name="submittedDate"/> <property name="trackingNumber"/> </filter> </bean>

<bean type="atg.commerce.order.ElectronicShippingGroup> <filter id="summary"> <property name="emailAddress"/> <property name="shippingAddress" hidden="true"/> </filter> <component> <!--

104 4 The REST MVC Definition Framework

<bean type="atg.commerce.order.HardgoodShippingGroup" super-type="atg.commerce.order.ShippingGroup"/> -- ></bean>

The Filter Element

The bean and item-descriptor elements contain one or more filter elements. To filter an item the same

way each time, define a single filter. To apply different filters on different occasions, define multiple filters under

the bean or item-descriptor with a different filter ID for each.

The filter element contains the following attributes:

Attribute Description

id The identifier for the filter when it is referenced by another filter, a default filter

setting or another actor.

include-filter Identifies the filter that is included in the property definition. The inclusion occurs at

all levels of the class hierarchy.

default-include Identifies whether or not to include all of the standard properties when obtaining

values for this component. The default is false, where only filtered properties will

be included.

Example: Referencing Another Filter Property By ID

You can reference a filter by ID when, for example, you want to return different views of the same object within

a single response. The following example shows how the product repository item in the ProductCatalog has

a relatedProducts property. However, this example does not want to return all properties of the product

item for each related product. This example shows that when a product item is filtered with the summary

filter ID, only the repositoryId, displayName and thumbnailImage properties are returned for the

relatedProducts property. Also note that the target attribute is used to rename properties:

<bean-filtering> <repository name="/atg/commerce/catalog/ProductCatalog"> <item-descriptor="product" default-filter="full"> <filter id="detailed"> <property name="repositoryId" target="id"/> <property name="displayName"/> <property name="longDescription"/> <property name="productDescription" target="description"/> <property name="thumbnailImage" target="thumbnailImage.url"/> <property name="fullImage" target="fullImage.url"/> <property name="largeImage" target="largeImage.url"/> <property name="relatedProducts" property-customizer="" filter-id="summary"/> </filter> <!-For related products we only want to output a small set of properties about the related products --> <filter id="shortSummary">

4 The REST MVC Definition Framework 105

<property name="repositoryId" target="id"/> <property name="displayName"/> <property name="thumbnailImage" target="thumbnailImage.url"/> </filter> </item-descriptor> </repository>

Note that the filter-id attribute of the filter element supersedes any filters that may have been applied in

the actor output definition.

Example: Referencing a Filter ID Using an Actor Definition

You can also reference a filter-id by including it within an actor definition. For example, if you wanted to

add a summary description to each product contained within a list of product results, apply a specific filter by

ID using the actor definition. The following example configures the output element to write to a list of product

repository item. The shortSummary filter, which was created in the previous example, will output the repository

ID, the display name, and thumbnail image.

<actor-template> <actor-chain> <component name="/atg/commerce/catalog/ExampleCatalogService" method="search" method-return-var="products"> <output name="products" value="${products}" filter-id="summary" /> </component> </actor-chain></actor-template>

To avoid having to duplicate property definitions that are shared among different filter descriptions, you can use

the include-filter attribute. This includes properties from another filter. For example, the detailed filter

could have been written so that the detailed filter includes the summary filter:

<bean-filtering> <repository name="/atg/commerce/catalog/ProductCatalog"> <item-descriptor="product" default-filter="full"> <filter id="detailed" include-filter="summary"> <property name="longDescription"/> <property name="productDescription" target="description"/> <property name="fullImage" target="fullImage.url"/> <property name="largeImage" target="largeImage.url"/> <property name="relatedProducts" property-customizer="" filter-id="summary"/> </filter> <!-For related products we only want to output a small set of properties about the related products --> <filter id="shortSummary"> <property name="repositoryId" target="id"/> <property name="displayName"/> <property name="thumbnailImage" target="thumbnailImage.url"/> </filter> </item-descriptor> </repository>

In this example, the repositoryId, displayName and thumbnailImage properties are not listed in the

detailed filter, but will still be included because the full filter now includes the summary filter using the

106 4 The REST MVC Definition Framework

filter-include attribute. Note that if a property is defined in both of the filters, the detailed filter will

override the summary filter when rendering.

The Property Element

The property element identifies which properties of repository items or beans should be included in the

response. By default, only properties that are explicitly listed are included.

The property element contains the following attributes:

Attribute Description

name The name that the property will use when sending the response.

target The name of the property that is read from the Java servlet bean or repository. If

no target is supplied, the value of the name attribute will be used instead.

property-

customizer

The Nucleus path of a component that implements the

atg.service.filter.bean.PropertyCustomizer interface. Use these

attributes to transform properties if needed.

hidden If this property is set to true, the property will be excluded from the response.

This property is set to false by default.

filter-id Applies a filter by ID that matches the class of the repository item type of the

property value. Note that the filter-id of a bean filter property will override

the filter-id attribute of an actor output element. Objects that are properties

of this element use this filter-id. For example, if a filter-id is applied to

the user repository-item, the same filter-id will be applied to the contact

repository-item when filtering the homeAddress property of the user.

Working with Property Customizers

You can transform properties using the property-customizer attribute. For example you could mask a credit

card number by creating a maskedCreditCardNumber property:

<property name="maskedCreditCardNumber" property-customizer="/atg/rest/ filtering/customizers/CreditCardNumberPropertyCustomizer" />

You can also retrieve other properties using this syntax.

If the target attribute does not start with a $, it will be evaluated as a DynamicBean.getPropertyValue() if

the object is a DynamicBean. Both item-descriptor and bean elements can use this syntax. Note that you

can add to any properties that are returned by default using XML combination.

You can use the RepositoryItemPropertyCustomzier to retrieve repository items or properties of a

repository item in a bean filter by looking up the item by ID. The following example retrieves a specific property

by specifying the property attribute:

4 The REST MVC Definition Framework 107

<property name="total" property-customizer="atg/dynamo/service/filter/bean/ RepositoryPropertyCustomizer" target="properties.orderId"> <attribute name="repository" value="/atg/commerce/order/OrderRepository" /> <attribute name="item-descriptor" value="order" /> <attribute name="property" value="priceInfo.amount" /></property>

To retrieve the entire repository item, do not specify a property attribute:

<property name="order" property-customizer="atg/dynamo/service/filter/bean/ RepositoryPropertyCustomizer" target="properties.orderId"> <attribute name="repository" value="/atg/commerce/order/OrderRepository" /> <attribute name="item-descriptor" value="order" /></property>

The DottedPropertyNamePropertyCustomizer can be used when you are working with properties that have

a dot in their name, such as profile.firstName. For example:

<property name="firstName" property-customizer="/atg/dynamo/service/filter/bean/ DotterPropertyNamePropertyCustomizer" target="properties.'profile.firstname'" />

The Attribute Element

The attribute element allows you to identify and pass name and value pair attributes for a property

customizer. This element contains the following attributes:

Attribute Description

name The name of the attribute.

value The value of the attribute.

Passing name and value attributes into a property-customizer is similar to passing attributes into a custom

repository-descriptor. For example, you can update the maskedCreditCardNumber property that was

created in The Property Element (page 106) section to identify the number of digits that are not masked when

displaying a credit card number:

<property name="maskedCreditCardNumber" property-customizer="/atg/rest/filtering/ customizers/CreditCardNumberProeprtyCustomizer"> <attribute name="unmaskedLength" value="4" /></property>

By creating this new attribute, when the credit card information is rendered, all but the last four numbers will be

masked.

108 4 The REST MVC Definition Framework

The Repository Element

The repository element defines one or more item-descriptor filters for a repository, and contains the following

attributes:

Attribute Description

name The path name to the repository.

item-descriptor The name of the item-descriptor to filter upon. The item-descriptor

elements are nested under the repository element so that item-descriptors

from the same repository are grouped together in the XML file. If you XML combine

any item-descriptor definitions, they are presented together under the

repository element in the combined XML.

The following is an example of the repository element:

<repository name="/atg/commerce/catalog/ProductCatalog"> <item-descriptor name="media-external" default-filter="summary"> <filter id="default"> <property name="url" /> <property name="mimeType" /> </filter> </item-descriptor></repository>

The alias element defines an alternate component path for the repository definition. The name attribute of the

alias element defines the path of the repository.

The Item-Descriptor Element

The item-descriptor element filters the properties returned for an item-descriptor placed in the

modelMap. It uses the following attributes:

Attribute Description

name The name of the item descriptor.

default-filter The ID of the default filter for this item-descriptor. If you define more than one

filter, specify a default filter to avoid errors in the case where no filter is specified in

the ModelMap.

The following is an example of the item-descriptor element:

<repository name="/atg/multisite/SiteRepository">

4 The REST MVC Definition Framework 109

<item-descriptor name="siteConfiguration"> <filter id="short"> <property name="id" /> <property name="name" /> </filter> </item-descriptor></repository>

Working with Filters

Use the Dynamo Server Admin to view the filters used in your environment. Select the /atg/dynamo/service/

filter/bean/XmlFilterService to see the filter configuration. Click on a repository or a servlet bean to view

filter information:

Note that you cannot use the Dynamo Server Admin to modify these filters. To make modifications to these

filters, modify the beanFilteringConfiguration.xml file. Once you have made the changes, use the

Dynamo Server Admin to access /atg/dynamo/service/filter/bean/BeanFilterService and run the

reinitialize method to implement your changes.

Configuring REST MVC Output

As described earlier, the ResponseGenerator transforms the information obtained from the actors

into a response. This response can be configured as either a JSON or XML response. Output from the

ResponseGenerator is configured using values from the /atg/dynamo/service/resonse/output/

110 4 The REST MVC Definition Framework

Configuration.properties file. The following configuration properties define the settings used for the

ResponseGenerator and output customizers:

Property Description

defaultFormat Sets the default output of the response to a specific format, such

as JSON or XML. The default for this property is json. Note that

this property is case sensitive. This property is overwritten if your

REST call contains the atg-rest-output parameter.

defaultTimeZoneId Sets the default time zone used when creating output dates. The

default for this property is GMT.

defaultEnableFormatDateOutput Use this property to configure output dates as formatted data

strings. The default is false, indicating that the output will

contain all of the properties of the Date object. This property uses

the defaultTimeZoneId for time zone output.

defaultMaxNestingDepth This property identifies how many levels the XML or JSON

response will contain. Setting this property to -1 sets the depth to

unlimited. The default of this property is set to 15.

REST MVC Access Control

Whenever an Oracle Commerce Platform REST MVC call occurs, the system checks the

AccessControllerService to determine if access to the URL should be granted for the given user. Access

control to REST MVC services is set with access controllers that are defined in the /atg/dynamo/servlet/

dafpipeline/

AccessControlServlet.

The access controller recognizes the /rest/model/ syntax and then maps the actor and call to a controller.

Example: External User Access Control

The following is an example of access control for an external user:

# List of mappings between paths and AccessController objects. If a# path refers to a directory, all the documents in that directory and# its subdirectories will be protected by the given AccessController.accessControllers+=\ /rest/model/atg/userprofiling/ProfileActor/logout= /atg/rest/userprofiling/LoggedInAccessController, \ /rest/model/atg/userprofiling/ProfileActor/logout-success= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/userprofiling/ProfileActor/logout-error= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/rest/SessionConfirmationActor/getSessionConfirmationNumber= /atg/rest/userprofiling/AllAccessController

4 The REST MVC Definition Framework 111

Example: Internal User Access Control

Access control for an internal user is provided by the InternalProfileActor. The following is an example of

access control for an internal user:

# List of mappings between paths and AccessController objects. If a# path refers to a directory, all the documents in that directory and# its subdirectories will be protected by the given AccessController.accessControllers+=\ /rest/model/atg/userprofiling/InternalProfileActor/login= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/userprofiling/InternalProfileActor/logout= /atg/rest/userprofiling/LoggedInAccessController, \ /rest/model/atg/userprofiling/InternalProfileActor/logout-error= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/userprofiling/SecurityConfirmationActor= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/rest/SessionConfirmationActor/getSessionConfirmationNumber= /atg/rest/userprofiling/AllAccessController, \ /rest/model=/atg/rest/userprofiling/NonTransientAccessController

accessControllers=+\ /rest/model/atg/userprofiling/ProfileActor/logout= /atg/rest/userprofiling/LoggedInAccessController, \ /rest/model/atg/userprofiling/ProfileActor/logout-success= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/userprofiling/ProfileActor/logout-error= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/rest/SessionConfirmationActor/getSessionConfirmationNumber =/atg/rest/userprofiling/AllAccessController

The following example of the /atg/rest/userprofiling/LoggedInAccessController shows how to set

the access controller using the enabled parameter, as well as which rule to use to determine access. If access is

denied, the SecurityStatusActor will identify the error and redirect the user to an error URL:

$class=atg.userprofiling.RuleAccessControllerenabled=true# Rules used to determine whether access should be allowedruleSetService=/atg/rest/targeting/LoggedInRuleSetService# URL to redirect to if access is denieddeniedAccessURL=/rest/model/atg/userprofiling/SecurityStatusActor/ authenticationRequired

Creating a New REST MVC Call

The following section identifies the steps needed to define a new REST MVC call.

1. Define an actor-chain component.

When you define an actor-chain component, it is recommended that you define it in the same location as

the component it references. For example:

112 4 The REST MVC Definition Framework

/atg/commerce/custsvc/order/CommitOrderActor.properties

$class=atg.service.actor.ActorChainService

definitionFile=commitOrderActor.xml

2. Define the actor-chain definition XML file.

It is best to define success and error URLs in the actor rather than on the client-side. You should also define a

success and error URL per form handler. You can use nested actors to reference a shared error handler.

<?xml version="1.0" encoding="UTF-8"?>

<actor-template default-chain-id="commitOrder"

xsi:noNamespaceSchemaLocation="http://www.atg.com/xsds/ActorChain.xsd"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<actor-chain id="commitOrder" transaction="TX_SUPPORTS">

<form id="commitOrderFormHandler"

name="/atg/commerce/custsvc/order/CommitOrderFormHandler"

handle="commitOrder" var="commitOrderFormHandler">

<input name="allowEmptyOrders" value="${param.allowEmptyOrders}"/>

<input name="salesChannel" value="${param.salesChannel}"/>

<input name="siteId" value="${param.siteId}"/>

<input name="commitOrderErrorURL"

value="/model/atg/commerce/custsvc/order/

CommitOrderActor/commitOrder-error"/>

<input name="commitOrderSuccessURL"

value="/model/atg/commerce/custsvc/order/

CommitOrderActor/commitOrder-success"/>

</form>

</actor-chain>

<actor-chain id="commitOrder-success" transaction="TX_SUPPORTS">

<actor id="success" name="/atg/commerce/custsvc/order/

OrderConfirmationActor" chain-id="orderConfirmation"

return-model-var="model">

<output id="model" add-map-children="true" value="${model}"/>

<actor>

</actor-chain>

<actor-chain id="commitOrder-error" transaction="TX_SUPPORTS">

<component id="fh" name="/atg/commerce/custsvc/order/

CommitOrderFormHandler" filter-id="full"/>

<output id="concurrentUpdate" name="concurrentUpdate"

value="${fh.concurrentUpdate}"/>

<output id="order" name="order" value="${fh.concurrentUpdate ?

fh.order : null}" filter-id="full"/>

</actor-chain>

</actor-template>

When creating a form handler, it is best to define success and error chains in the base directory, such as /DCS,

and then XML combine the success chain in your Web application directory.

Note that when you are creating an actor-chain component in development mode, it is best to disable the

Dynamo session confirmation number. To do this, disable the enforceSessionConfirmation parameter in

your local /atg/dynamo/service

/actor/Configuration.properties file. Once you have finished testing the component, you can set the

property back to use session confirmation. Refer to the Using Dynamo Session Confirmation Numbers (page

70) section for further information.

4 The REST MVC Definition Framework 113

3. If required, create a success chain using XML combination in the Web application directory.

For example, the following example displays an order confirmation after the order has been committed.

<actor-template default-chain-id="commitOrder">

<actor-chain id="comittOrder-error" transaction="TX_SUPPORTS">

</actor-chain>

<actor-chain id="commitOrder-success">

<actor id="success" name="/atg/commerce/custsvc/order/

OrderConfirmationActor" chain-id="orderConfirmation"

return-model-var="model"/>

<output id="model" add-map-children="true" value="${model}"/>

</actor>

</actor-chain>

</actor-template>

4. Register the actor-chains in the ActorChainRestRegistry so that they are enabled for REST access.

By default, no actors are registered. Actor-chains accessed from REST or from success and error URLs must be

registered in the application module. Actor-chains that are accessed only from nested actors do not need to

be registered. Note that each chain ID should be registered separately. For information on registering actors,

refer to the Enabling REST Services (page 69) section.

# /atg/rest/registry/ActorChainRestRegistry.properties

registeredUrls+=\

/atg/commerce/custsvc/order/CommitOrderActor/commitOrder, \

/atg/commerce/cstsvc/order/CommitOrderActor/

commitOrder-success, \

/atg/commerce/custsvc/order/CommitOrderActor/

commitOrder-error

5. Define the Java servlet bean filters.

Bean filters are shared across all actor calls. Use a separate filter ID if you need a specific view for a specific

actor. It is best to define properties per class, as filtering will be applied to each class or interface in the class

hierarchy. You can define filters for both repository items and any wrapper classes that you may have for

repository items.

<bean name="atg.commerce.order.Order" default-filter="summary">

<filter id="summary">

<property name="commerceItems"/>

<property name="priceInfo"/>

<property name="totalCommerceItemCount"/>

</filter>

<filter id="full">

<property name="commerceItems"/>

<property name="creationTime"/>

<property name="id"/>

<property name="lastModifiedTime"/>

<property name="paymentGroupCount"/>

<property name="paymentGroups"/>

<property name="priceInfo"/>

<property name="profileId"/>

<property name="relationships"/>

<property name="shippingGroupCount"/>

<property name="shippingGroups"/>

114 4 The REST MVC Definition Framework

<property name="siteId"/>

<property name="stateDetailAsUserResource"/>

<property name="taxPriceInfo"/>

<property name="totalCommerceItemCount"/>

</filter>

</bean>

Note that you can enable debugging when creating your filter by setting the loggingDebug attribute to

true in the /atg/dynamo/service/filter/

bean/BeanFilterService. This will provide a log of what is being filtered.

6. Test your new REST call.

When you have created your new REST call, you can test it using cURL. For information on creating cURL

examples, refer to the Using cURL for Examples (page 59) section. It is best to test success and the error

conditions, as well as JSON or XML input and output types. For example, you can test the new Commit Order

call using the following cURL:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"

"http://localhost:8280/rest/model/atg/commerce/custsvc/order/

CommitOrderActor/commitOrder {"orderId": {"orderId":

"o99520004"}}"

During your development and testing, you may want to disable the Dynamo session confirmation numbers,

as discussed in the Using Dynamo Session Confirmation Numbers (page 70) section. To disable the session

confirmation numbers, set the enforceSessionConfirmation parameter in your local /atg/dynamo/

service

/actor/Configuration.properties file to false. Note that the following type of ambiguous error will

occur when session confirmation is disabled:

HTTP Status 409 - Your session expired due to inactivity.type - Status reportmessage - Your session expired due to inactivity.description - The request could not be completed due to a conflict with thecurrent state of the resource.

5 External REST MVC Service Call Examples 115

5 External REST MVC Service Call

Examples

The following REST MVC services have been made available so that you can begin issuing them immediately

upon installation of your REST configuration.

As described in previous sections, REST MVC calls are based on actors that perform specific functions. This

section is organized by tasks that each actor performs for external-facing customers. For REST MVC calls for

agents, refer to the Internal REST MVC Service Call Examples (page 179) section.

Note that this section contains information on desktop REST MVC calls. For information on REST calls used by

mobile applications, refer to the Commerce Reference Store IUA Overview document.

External Service Call Workflow Example

The following diagram shows an example of a typical customer’s workflow that contains various REST service

calls:

Each of these service calls performs an action within the Add Item to Cart workflow, starting with a customer

logging in to the REST server and ending when the customer logs out of the REST server.

116 5 External REST MVC Service Call Examples

Note: The following examples are provided as guidelines for working with External REST MVC calls. The

responses returned by your server may vary based upon your environment’s configuration.

Getting the Session Confirmation Number

The first actor that must be invoked is the Dynamo Session Confirmation actor. As described in the Using

Dynamo Session Confirmation Numbers (page 70) section, the session confirmation number is used by

the REST Web Services to provide secure access to the REST calls. The Form Element (page 84) and The

Component Element (page 77) use _dynSessConf for method calls and setting property values. The

SessionConfirmationActor returns the session confirmation number. The path to this actor is /atg/rest

and it uses the getSessionConfirmationNumber actor-chain.

Parameters: None

Session Confirmation Number Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/rest/SessionConfirmationActor/getSessionConfirmationNumber"

The server response may be similar to the following:

{"sessionConfirmationNumber":-5166444348429687167}

Specifying Site Context in a Multisite Environment

Include the pushSite URL query parameter to specify site context when performing an external REST call.

Include the site as the value of the pushSite parameter. For detailed information about the pushSite

parameter, refer to Multisite Request Processing section of the Platform Programming Guide.

For example, to set the site context to mainStoreUS:

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/rest/ShoppingCartActor/totalCommerceItemCount?pushSite=mainStoreUS"

Working with Customers

The ProfileActor allows you to access and work with customer profiles. This actor is located at /atg/

userprofiling/ and contains the following actor-chains:

5 External REST MVC Service Call Examples 117

Actor-Chain Description

login Allows a customer to log into the site.

logout Allows a customer to log out of a site.

create Creates a customer profile.

update Updates a customer profile.

detailed Views a customer profile using the detailed filter.

summary Views a customer profile using the summary filter.

creditCards Provides the credit cards associated with the customer profile.

currentCatalog Provides the customer’s current catalog.

addresses Provides the addresses associated with this customer profile.

Logging In Customers

The login actor-chain is used to log the customer into the site and verify the appropriate login and password

credentials.

Parameter Description

login The customer login, for example, user@example.com.

password The customer’s password.

Customer Log In Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"-d "{ \"login\" : \"JohnDoe@example.com\" , \"password\" : \"password123\" }""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/login"

If the log in information is incorrect, the following exception might occur:

{"formError":true,"formExceptions":[{"localizedMessage":"The password andlogin do not match","errorCode":"invalidPassword"}]}

Logging Out Customers

The logout actor-chain is used to log the customer out of the application.

118 5 External REST MVC Service Call Examples

Parameters: None

Customer Log Out Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/logout"

Creating New Customer Profiles

The create actor-chain is used to create a new customer profile.

Parameter Description

autoLogin Determines if a cookie should be returned upon logging in. This

property, if set to true, allows customer to log in automatically.

realmId If your environment is set up to use profile realms, this indicates the

ID of the realm. Refer to the Core Commerce Programming Guide for

information on profile realms.

firstName The first name of the customer.

middleName The middle name or initial of the customer.

lastName The last name of the customer.

email The customer’s e-mail address.

password The customer’s password.

confirmPassword Re-enter the customer’s password to verify.

login The customer’s log in name.

dateOfBirth The customer’s date of birth.

gender The customer’s gender.

homeAddress.address1 The first address line of the customer’s home address.

homeAddress.address2 The second address line of the customer’s home address.

homeAddress.address3 The third address line of the customer’s home address.

homeAddress.city The city associated with the customer’s home address.

homeAddress.state The state associated with the customer’s home address.

homeAddress.postalCode The postal code associated with the customer’s home address.

homeAddress.country The country associated with the customer’s home address.

5 External REST MVC Service Call Examples 119

Parameter Description

homeAddress.phoneNumber The phone number of the customer’s home address.

homeAddress.companyName A company that is associated with the home address.

homeAddress.county A county that it associated with the home address.

homeAddress.jobTitle A job title associated with the customer’s home address.

homeAddress.faxNumber A fax number associated with the customer’s home address.

homeAddress.prefix A prefix used when creating the home address, for example, Mr. or Dr.

homeAddress.suffix A suffix used when creating the user name associated with the home

address, for example, Jr.

homeAddress.firstName The first name of the customer associated with the home address.

homeAddress.middleName A middle name or initial of the customer associated with the home

address.

homeAddress.lastName The last name of the customer associated with the home address.

daytimeTelephoneNumber Identifies the daytime telephone number on the customer profile.

Create Customer Profile Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"{\"firstName\":\"Joe\", \"middleName\":\"T\", \"lastName\":\"Smith\",\"email\":\"jsmith@example.com\", \"password\":\"tempPassword\",\"confirmPassword\":\"tempPassword\", \"login\":\"joe03\", \"homeAddress\":{\"atg-rest-class-type\":\"java.util.HashMap\", \"atg-rest-values\":{\"address1\":\"111 Main Street\", \"address2\":\"Suite 100\",\"city\":\"Cambridge\", \"state\":\"MA\", \"country\":\"USA\",\"postalCode\":\"00123\", \"phone\": \"555-111-2222\"}} }""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/create"

Editing or Updating a Customer Profile

The update actor-chain is used to edit customer profiles.

Parameter Description

autoLogin Determines if a cookie should be used when logging in. Setting this to

true allows a customer to log in automatically.

120 5 External REST MVC Service Call Examples

Parameter Description

realmId If your environment is set up to use realms, this indicates the ID of the

realm. Refer to the Core Commerce Programming Guide for information

on realms.

firstName The first name of the customer.

middleName The middle name or initial of the customer.

lastName The last name of the customer.

email The customer’s e-mail address.

password The customer’s password.

confirmPassword Re-enter the customer’s password to verify.

login The customer’s log in name.

dateOfBirth The customer’s date of birth.

gender The customer’s gender.

homeAddress.address1 The first address line of the customer’s home address.

homeAddress.address2 The second address line of the customer’s home address.

homeAddress.address3 The third address line of the customer’s home address.

homeAddress.city The city associated with the customer’s home address.

homeAddress.state The state associated with the customer’s home address.

homeAddress.postalCode The postal code associated with the customer’s home address.

homeAddress.country The country associated with the customer’s home address.

homeAddress.phoneNumber The phone number of the customer’s home address.

homeAddress.companyName A company that is associated with the home address.

homeAddress.county A county that is associated with the home address.

homeAddress.jobTitle A job title associated with the customer’s home address.

homeAddress.faxNumber A fax number associated with the customer’s home address.

homeAddress.prefix A prefix associated with the customer when creating the home address,

for example, Mr. or Dr.

homeAddress.suffix A suffix to display for the customer when displaying the home address,

for example, Jr.

homeAddress.firstName The first name of the customer associated with the home address.

5 External REST MVC Service Call Examples 121

Parameter Description

homeAddress.middleName A middle name or initial of the customer associated with the home

address.

homeAddress.lastName The last name of the customer associated with the home address.

daytimeTelephoneNumber Identifies the daytime telephone number on the customer profile.

Edit Customer Profile Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"{\"firstName\":\"Joe\", \"middleName\":\"B\", \"lastName\":\"Smith\",\"email\":\"jsmith@example.com\", \"daytimeTelephoneNumber\":\"617-637-8687\",\"homeAddress\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\": {\"address1\":\"127 Main Street\", \"address2\":\"Suite 100\", \"city\":\"Cambridge\",\"state\":\"MA\", \"country\":\"USA\",\"postalCode\":\"02046\", \"phone\": \"555-111-3333\"}} }""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/update"

Viewing a Customer Profile

The detailed actor-chain is used to view customer profiles.

Parameters: None

View Customer Profile Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/detailed"

Viewing the Shopping Cart

The ShoppingCartActor contains two chains, the detailed actor-chain that is used to view or review a cart or

order, and the summary actor-chain that provides a summary of the shopping cart. This actor is located at /atg/

commerce/.

Parameters: None

View Shopping Cart Example

The following example shows a detailed request:

curl -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/ShoppingCartActor/detailed"

122 5 External REST MVC Service Call Examples

The server response may be similar to the following:

{"order": { "lastModifiedTime": 1363293103777, "shippingGroupCount": 1, "paymentGroupCount": 1, "shippingGroups": [{ "specialInstructions": {}, "handlingInstructions": [], "state": 0, "locationId": null, "shippingMethod": "Ground", "id": "sg140009", "trackingNumber": null, "priceInfo": null, "description": "sg140009", "actualShipDate": null, "submittedDate": null, "shipOnDate": null, "shippingAddress": { "middleName": null, "lastName": "Smith", "ownerId": null, "state": "MA", "address1": "1 Main Street", "address2": null, "address3": null, "companyName": null, "suffix": null, "city": "Cambridge", "country": "USA", "id": null, "postalCode": "02046", "faxNumber": null, "phoneNumber": "6176378687", "county": null, "email": "jsmith@example.com", "prefix": null, "firstName": "John", "jobTitle": null }, "stateDetail": null }], "commerceItems": [{ "id": "ci11000002", "productDisplayName": "Roseanna Storage Ottoman", "returnedQuantity": 0, "priceInfo": { "amount": 159.2, "quantityDiscounted": 1, "discountable": true, "priceListId": "listPrices", "onSale": false, "rawTotalPrice": 199, "currencyCode": "USD", "amountIsFinal": false, "listPrice": 199, "discounted": true, "currentPriceDetailsSorted": [{

5 External REST MVC Service Call Examples 123

"amount": 159.2, "itemPriceInfo": null, "currencyCode": "USD", "tax": 0, "range": { "lowBound": 0, "class": "atg.core.util.Range", "highBound": 0, "size": 1 }, "amountIsFinal": false, "discounted": true, "quantity": 1, "detailedUnitPrice": 159.2 }], "salePrice": 0 }, "catalogId": null, "quantity": 1, "catalogRefId": "xsku2034", "catalogKey": "en_US", "productId": "xprod2034" }], "id": "o140002", "siteId": "homeSite", "taxPriceInfo": null, "priceInfo": { "amount": 149.2, "total": 149.2, "shipping": 0, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": true, "manualAdjustmentTotal": 0, "rawSubtotal": 159.2, "discountAmount": 10 }, "paymentGroups": [{ "amount": 0, "currencyCode": null, "expirationMonth": null, "expirationYear": null, "paymentId": "pg140003", "creditCardNumber": null, "expirationDayOfMonth": null, "billingAddress": { "middleName": null, "lastName": "Smith", "ownerId": null, "state": "MA", "address1": "1 Main Street", "address2": null, "address3": null, "companyName": null, "suffix": null, "city": "Cambridge", "country": "USA", "id": null, "postalCode": "02046",

124 5 External REST MVC Service Call Examples

"faxNumber": null, "phoneNumber": "6176378687", "county": null, "email": "jsmith@example.com", "prefix": null, "firstName": "John", "jobTitle": null }, "creditCardType": "Visa", "orderId": null }], "profileId": "230000", "creationTime": 1363291121877, "relationships": [{ "id": "r110006", "amount": 0, "relationshipType": "SHIPPINGQUANTITY", "returnedQuantity": 0, "shippingGroupId": "sg140009", "commerceItemId": "ci11000002", "quantity": 1 }], "totalCommerceItemCount": 1}}

Working with the Shopping Cart

The CartModifierActor contains several actor-chains that modify the customer’s shopping cart. The path for

this actor is /atg/commerce/order/purchase/CartModifierActor.

This actor contains the following actor-chains:

Actor-Chain Description

addItemToOrder Adds items from a catalog, wish/gift list to a shopping

cart.

addMultipleItemsToOrder Adds multiple items to a shopping cart.

moveToPurchaseInfo Saves the shopping cart and continues to the next step in

the checkout process.

moveToPurchaseInfoByCommerceId Saves the shopping cart and continues to the next step in

the checkout process.

moveToPurchaseInfoByRelId Saves the shopping cart and continues to the next

step in the checkout process using the shipping group

relationship ID.

removeAndAddItemToOrder Removes an item and then adds it to the shopping cart.

5 External REST MVC Service Call Examples 125

Actor-Chain Description

removeItemFromOrder Removes an item from the shopping cart using the SKU ID.

removeItemFromOrderByRelationshipId Removes an item from the shopping cart using the

relationship ID.

setOrder Updates the shopping cart by SKU ID.

setOrderByCommerceId Updates the shopping cart by commerce ID.

setOrderByRelationshipID Updates the shopping cart by relationship ID.

Adding Multiple Items to the Shopping Cart

The addMultipleItemsToOrder actor-chain is used when adding more than one item to shopping cart.

Parameter Description

addItemCount The number of items being added to the shopping cart. This is different than the

quantity of each product being added.

catalogRefId The catalog reference ID.

giftlistId Used only when adding gift or wishlist items to the shopping cart. Identifies the ID of

the list.

giftlistItemId Used only when adding gift or wishlist items to the shopping cart. Identifies the ID of

the list item.

locationId Used only for in-store pickup. This identifies the location of the store.

productId The ID of the product to add to the shopping cart.

quantity The number of each product being added to the shopping cart. For example, two

sweaters or four pairs of shoes.

quantityWith

Fraction

The number of each product being added to the shopping cart, but in fractional

quantities. For example, a half gallon of milk.

Add Multiple Items to Order Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"addItemCount\": 3, \"items\": {\"atg-rest-class-type\":\"java.util.ArrayList\",\"atg-rest-values\": [{\"atg-rest-class-type\":\"atg.commerce.order.purchase.AddCommerceItemInfo\", \"catalogRefId\":\"xsku1043\",\"productId\": \"xprod1015\",\"quantity\": 1},{\"atg-rest-class-type\": \"atg.commerce.order.purchase.AddCommerceItemInfo\",\"catalogRefId\": \"xsku60325\",\"productId\": \"xprod40028\",\"quantity\": 2},

126 5 External REST MVC Service Call Examples

{\"atg-rest-class-type\": \"atg.commerce.order.purchase.AddCommerceItemInfo\",\"catalogRefId\": \"xsku1001\",\"productId\": \"xprod1001\",\"quantity\": 3} ]}}""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/addMultipleItemsToOrder"

Adding an Item to a Shopping Cart

The addItemToOrder actor-chain is used to add a single item to a shopping cart. It also is used to add an item

from a customer’s gift/wish list to a shopping cart, as well as adding an item to an in-store pickup order:

Parameter Description

addToWishlist Boolean parameter used only for adding wish list items to the shopping cart.

catalogRefIds The catalog reference ID.

giftlistId Used only when adding gift or wishlist items to the shopping cart. Identifies the gift

list ID.

giftlistItemId Used only when adding gift or wishlist items to the shopping cart. Identifies the ID of

the list item.

locationId Used only for in-store pickup, identifies the location of the store.

productId The ID of the product to add to the shopping cart.

quantity The number of each product being added to the shopping cart. For example, two

sweaters or four pairs of shoes.

quantityWith

Fraction

The number of each product being added to the shopping cart, but in a fractional

amount. For example, a half pound of sugar or ¼ gallon of fuel.

Add Item to Order Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\": \"xsku1043\",\"productId\":\"xprod1015\",\"quantity\": 1}""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder"

Add Item to In-Store Pickup Example

Note the use of the locationId to identify the store from where the item will be picked up.

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\": \"sku30029\",\"productId\": \"prod10004\", \"locationId\":\"FashionIsland\", \"quantity\": 1}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder"

5 External REST MVC Service Call Examples 127

Add Item From Gift List Example

Note the use of the giftlistId and the giftlistItemId.

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\" : \"xsku2085\", \"productId\" : \"xprod2085\", \"giftlistId\" :\"gl40007\",\"giftlistItemId\" : \"gi40001\", \"quantity\": 1}""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder"

Add Item From Wish List Example

This example is similar to the Gift List example, however if addToWishlist is true, the system uses

Profile.wishlist.repositoryId instead of the giftlistId.

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\" : \"xsku2085\", \"productId\" : \"xprod2085\",\"addToWishlist\" : \"true\",\"giftlistItemId\" : \"gi40001\", \"quantity\": 1}""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder"

Updating the Shopping Cart by SKU ID

The setOrder actor-chain updates the quantity of items within the cart using SKU IDs.

Parameters: None

Update Shopping Cart by SKU ID Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/setOrder?xsku1043=2"

Updating the Shopping Cart by Commerce ID

The setOrderByCommerceId actor-chain updates the quantities of items within the cart using the commerce

ID.

Parameters: None

Update Shopping Cart by Commerce ID Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/setOrderByCommerceId?ci111000001=3"

128 5 External REST MVC Service Call Examples

Updating the Shopping Cart By Shipping Group Relationship ID

The setOrderByRelationshipId actor-chain is used to update the quantities of items within the cart using

the CommerceItem or the shipping group relationship ID.

Parameters: None

Update Shopping Cart by Relationship ID Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/setOrderByRelationshipId?r99090004=4"

Removing and Adding an Item to the Cart

The removeAndAddItemToOrder actor-chain is used to remove items from the order and then add it back to

the order.

Parameter Description

catalogRefIds The catalog reference ID.

productId The ID of the product.

quantity The quantity of the product.

quantityWithFraction The quantity of the product in fractional units.

removalCommerceIds The list of commerce IDs to remove.

Move Item to the Cart Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\":\"xsku1043\",\"productId\": \"xprod1015\",\"quantity\": 1,\"removalCommerceIds\":\"ci116000002\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/removeAndAddItemToOrder"

Removing an Item From the Shopping Cart

The removeItemFromOrder actor-chain removes items from the cart using the commerce ID.

Parameters: None

Remove Item From Cart Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"

5 External REST MVC Service Call Examples 129

"http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/removeItemFromOrder?removalCommerceIds=ci115000001"

Removing an Item From the Shopping Cart By Relationship ID

The removeItemFromOrderByRelationshipId actor-chain is used to remove items from the cart using the

CommerceItem or the shipping group relationship ID.

Parameters: None

Remove Item by Relationship ID Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/removeItemFromOrderByRelationshipId?removalRelationshipIds=r99160002"

Starting the Checkout Process

The moveToPurchaseInfoByCommerceId actor-chain starts the checkout process. The current order’s

commerce items and quantities must be passed in to initiate the checkout process.

Parameters: None

Continue the Checkout Process Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"http://localhost:8280/rest/model/atg/commerce/order/purchase/CartModifierActor/moveToPurchaseInfoByCommerceId"

Working with the Shipping Page

The ShippingGroupActor contains several actor-chains that modify the Shipping page. The path for this actor

is /atg/commerce/order/purchase/ShippingGroupActor.

This actor contains the following actor-chains:

Actor-Chain Description

getShippingGroups Displays the shipping groups that are available.

specifyDefaultShippingGroup Specifies a default shipping group.

applyDefaultShippingGroup Applies the default shipping group.

130 5 External REST MVC Service Call Examples

Actor-Chain Description

getAllCommerceItemShippingInfos Obtains all of the Commerce Item Shipping Info (CISI).

applyShippingGroups Applies the shipping group.

splitShippingInfos Splits the shipping between specified shipping groups.

Supports fractional quantities.

Displaying Shipping Groups

The GetShippingGroups actor-chain displays all of the shipping groups that are available.

Parameter Description

createOneInfoPerUnit A Boolean parameter that controls if one Commerce Item Shipping Info

(CISI) is created for each item unit. For example, if you add an item with a

quantity of five, you will end up with five CommerceItemShippingInfos,

each with a quantity of one.

init If set to true, clears shippingInfos and shippingGroups and

reinitializes these values in the /atg/commerce/order/purchase/

ShippingGroupDroplet.

shippingGroupTypes Identifies the shipping group types.

Display Shipping Groups Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"createOneInfoPerUnit\":\"true\", \"init\":\"true\", \"shippingGroupTypes\":\"hardgoodShippingGroup\" }" "http://localhost:8280/rest/model/atg/commerce/order/purchase/ShippingGroupActor/getShippingGroups"

The server response may be similar to the following:

{ "shippingGroups": {"Test": { "specialInstructions": {}, "priceInfo": { "amount": 0, "currencyCode": null, "amountIsFinal": false, "discounted": false }, "description": "sg140012", "actualShipDate": null, "submittedDate": null, "state": 0, "locationId": null,

5 External REST MVC Service Call Examples 131

"shipOnDate": null, "shippingMethod": "hardgoodShippingGroup", "shippingAddress": { "lastName": "Smith", "postalCode": "02046", "phoneNumber": "6176378687", "email": "jsmith@example.com", "state": "MA", "address1": "1 Main St", "address2": null "firstName": "John", "city": "Cambridge", "country": "USA" }, "stateDetail": null }}, "shippingInfos": {"ci11000002": [{ "handlingInstructionInfos": [], "commerceItemId": "ci11000002" }]}}

Specifying the Default Shipping Group

The specifyDefaultShippingGroup actor-chain identifies the default shipping group for the current order.

Parameter Description

defaultShippingGroupName Identifies the default shipping group name.

Specify Default Shipping Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"defaultShippingGroupName\" : \"Address\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/ShippingGroupActor/specifyDefaultShippingGroup"

Applying the Default Shipping Group

The applyDefaultShippingGroup actor-chain applies shipping of the order to the default shipping group.

Note: You cannot use applyDefaultShippingGroup to set the a shipping method. To set the

shipping method, choose the method used in the getCommerceIdentifierShippingInfos and

applyShippingGroup parameters.

Parameters: None

Apply Default Shipping Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"

132 5 External REST MVC Service Call Examples

"http://localhost:8280/rest/model/atg/commerce/order/purchase/ShippingGroupActor/applyDefaultShippingGroup"

Obtaining the Current Shipping Info List

The getAllCommerceItemShippingInfos actor-chain obtains all of the Commerce Item Shipping Info (CISI).

Note that you must call this method to initialize the shipping list prior to calling applyShippingGroups.

Parameters: None

Initialize Shipping List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/ShippingGroupActor/getAllCommerceItemShippingInfos"

Applying Shipping Groups and Shipping Methods

The ApplyShippingGroups actor-chain applies single or multiple shipping groups and shipping methods and

then continues onto the billing process. This chain is also used to apply multiple shipping groups or methods.

Parameter Description

cisicount Identifies the array size, or number of Commerce Item Shipping

Info (CISI) items included in the request.

cisiList.shippingGroupName Identifies the name of the shipping group.

cisiList.shippingMethod Identifies the shipping method used for the shipping group.

Apply Shipping Group and Method Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"cisicount\" : \"2\", \"cisiList\" :{ \"atg-rest-class-type\" :\"java.util.ArrayList\", \"atg-rest-values\": [{\"atg-rest-class-type\" :\"atg.commerce.order.purchase.CommerceItemShippingInfo\", \"shippingGroupName\" :\"Home\", \"shippingMethod\" : \"Ground\"}, {\"atg-rest-class-type\" :\"atg.commerce.order.purchase.CommerceItemShippingInfo\", \"shippingGroupName\" :\"Work\", \"shippingMethod\" : \"Ground\"}]}}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/ShippingGroupActor/applyShippingGroups"

Splitting Commerce Items into Different Shipping Groups

The splitShippingInfos actor-chain splits the shipping between shipping groups.

5 External REST MVC Service Call Examples 133

Parameter Description

cisiList.quantity The original quantity value that needs to be split.

cisiList.splitQuantity The quantity that should be moved to the other shipping

group.

cisiList.shipppingGroupName This is the name of the shipping group in which the item

will be available.

cisiList.splitShippingGroupName This is the name of the split shipping group.

Split Commerce Items into Different Shipping Groups Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"cisicount\" : \"1\", \"cisiList\" :{ \"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\": [{ \"atg-rest-class-type\":\"atg.commerce.order.purchase.CommerceItemShippingInfo\", \"quantity\" : \"5\",\"splitQuantity\" : \"2\", \"shippingGroupName\" : \"Address\",\"splitShippingGroupName\" : \"Address##0\"}]}}""http://localhost:8280/rest/model/atg/commerce/order/purchase/ShippingGroupActor/splitShippingInfos"

Displaying Available Shipping Methods

The AvailableShippingMethodsActor is used to display the available shipping methods. The path to this

actor is: /atg/commerce/pricing/AvailableShippingMethodsActor.

This actor contains the getAvailableShippingMethods actor-chain:

Parameters: None

Display Available Shipping Methods Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/pricing/AvailableShippingMethodsActor/getAvailableShippingMethods"

Creating a New Hardgood Shipping Group

The CreateHardgoodShippingGroupActor is used to create a new shipping group. The path to this actor is: /

atg/commerce/order/purchase/CreateHardgoodShippingGroupActor.

This actor contains the addHardgoodShippingGroup actor-chain.

Parameter Description

hardgoodShippingGroupName The name of the shipping group.

134 5 External REST MVC Service Call Examples

Parameter Description

hardgoodShippingGroupType The shipping group type.

firstName The first name of the customer associated with this shipping group.

middleName The middle name or initial of the customer associated with this

shipping group.

lastName The last name of the customer associated with this shipping group.

address1 The first address field associated with this shipping group.

address2 The second address field associated with this shipping group.

city The city of the address associated with this shipping group.

state The state of the address associated with this shipping group.

country The country of the address associated with this shipping group.

postalCode The postal code of the address associated with this shipping group.

phoneNumber The phone number of the customer associated with this shipping

group.

Create New Shipping Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"firstName\": \"John\",\"lastName\": \"Doe\", \"address1\": \"1 Main St.\",\"city"\:\"Cambridge\", \"state\": \"MA\", \"country\": \"USA\",\"postalCode\":\"02146\" }""http://localhost:8280/rest/model/atg/commerce/order/purchase/CreateHardgoodShippingGroupActor/addHardgoodShippingGroup"

Editing a Shipping Group

The UpdateHardgoodShippingGroupActor is used to edit shipping groups. The path to this actor is: /atg/

commerce/order/purchase/UpdateHardgoodShippingGroupActor.

This actor contains the updateHardgoodShippingGroup actor-chain:

Parameter Description

nickname The nickname associated with the shipping group to update.

firstName The first name of the customer associated with this shipping group.

middleName The middle name or initial of the customer associated with this shipping group.

lastName The last name of the customer associated with this shipping group.

5 External REST MVC Service Call Examples 135

Parameter Description

address1 The first address field of the address associated with this shipping group.

address2 The second address field of the address associated with this shipping group.

city The city of the address associated with this shipping group.

state The state of the address associated with this shipping group.

country The country of the address associated with this shipping group.

postalCode The postal code of the address associated with this shipping group.

phoneNumber The phone number of the customer associated with this shipping group.

Edit Shipping Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"nickname\": \"Address\",\"firstName\": \"John\",\"lastName\":\"Doe\",\"address1\": \" 2 Main St.\",\"city\": \"Wilmington\",\"state\":\"MA\",\"country\": \"USA\",\"postalCode\": \"01872\" }""http://localhost:8280/rest/model/atg/commerce/order/purchase/UpdateHardgoodShippingGroupActor/updateHardgoodShippingGroup"

Working with the Billing Page

The PaymentGroupActor contains several actor-chains that allow the customer to work with the billing page,

and to specify payment groups. The path for this actor is /atg/commerce/order/purchase/

PaymentGroupActor.

This actor contains the following actor-chains:

Actor-Chain Description

getPaymentGroups Displays the Billing page.

specifyDefaultPaymentGroup Specifies the default payment group.

applyDefaultPaymentGroup Applies the default payment group.

getCommerceIdentifierPaymentInfos Gets the Commerce Identifier Payment Info (CIPI).

applyMultiplePaymentGroups Applies single or multiple payment groups.

136 5 External REST MVC Service Call Examples

Display the Billing Page

The getPaymentGroups actor-chain is used to display the Billing page.

Parameter Description

init This Boolean parameter, if true, will clear payment group information and

the Commerce Identifier Payment Info (CIPI) , and initialize payment groups

and the Commerce Item Shipping Info (CISI).

createAllPaymentInfos This parameter will look for all Commerce Identifier Payment Info (CIPI), and

returns information from all payment groups.

paymentGroupTypes Identifies the payment group types, such as creditCard or storeCredit.

Display Billing Page Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{ \"init\" : \"true\", \"paymentGroupTypes\" : \"creditCard,storeCredit\"}""http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/getPaymentGroups"

The server response may be similar to the following:

{"paymentGroups": {"Visa": { "amount": 109.2, "currencyCode": "USD", "expirationMonth": "1", "expirationYear": "2014", "paymentId": "pg140002", "creditCardNumber": "1111", "expirationDayOfMonth": null, "billingAddress": { "lastName": "Smith", "postalCode": "02046", "phoneNumber": "6176378687", "email": "jsmith@example.com", "state": "MA", "address1": "1 Main St", "address2": "", "firstName": "John", "city": "Cambridge", "country": "USA" }, "creditCardType": "Visa", "orderId": null}}}

5 External REST MVC Service Call Examples 137

Specifying the Default Payment Group

The specifyDefaultPaymentGroup actor-chain is used to identify the default payment group.

Parameter Description

defaultPaymentGroupName Identifies the default payment group name.

Specify Default Payment Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{\"defaultPaymentGroupName\" : \"visa 1111\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/specifyDefaultPaymentGroup"

Applying Default Payment Group

The applyDefaultPaymentGroup actor-chain is used to apply the default payment group to the order and

continues on to order review.

Parameters: None

Apply Default Payment Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/applyDefaultPaymentGroup"

The server response may be similar to the following:

{"paymentGroups": {"visa - 1111": {{"paymentGroups": {"visa - 1111": { "amount": 0, "currencyCode": null, "expirationMonth": "1", "expirationYear": "2022", "paymentId": "pg110012", "creditCardNumber": "1111", "expirationDayOfMonth": null, "billingAddress": { "lastName": "Smith", "postalCode": "02046", "phoneNumber": "6176378687", "email": "jsmith@example.com", "state": "MA", "address1": "1 Main Street", "address2": null, "firstName": "John", "city": "Cambridge", "country": "USA" }, "creditCardType": "Visa",

138 5 External REST MVC Service Call Examples

"orderId": null}}}

"orderId": null

Obtaining Current Payment Info Lists

Th getCommerceIdentifierPaymentInfos actor-chain is used to obtain the Commerce Identifier Payment

Info (CIPI) list, based on the commerce item-identifier, such as Order ID, or Commerce Item ID.

Parameter Description

listId Identifies the payment list to initialize.

Initialize Payment List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{ \"listId\" : \"o60003\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/getCommerceIdentifierPaymentInfos"

The server response may resemble the following:

{"currentList": [ { "amount": 0, "relationshipType": "ORDERAMOUNTREMAINING", "splitQuantity": 0, "quantity": 0, "amountRemainingType": "ORDERAMOUNTREMAINING", "splitAmount": 0, "commerceIdentifier": { "id": "o60004", "priceInfo": { "amount": 5, "total": 5, "shipping": 0, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": false, "manualAdjustmentTotal": 0, "rawSubtotal": 5, "discountAmount": 0, "adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }] },

5 External REST MVC Service Call Examples 139

"commerceItems": [{ "id": "ci7000008", "productDisplayName": "Gift Wrap", "returnedQuantity": 0, "priceInfo": { "quantityDiscounted": 0, "quantityAsQualifier": 0, "onSale": false, "currencyCode": "USD", "orderDiscountShare": 0, "adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }], "amount": 5, "discountable": null, "rawTotalPrice": 5, "listPrice": 5, "amountIsFinal": false, "discounted": false, "salePrice": 0 }, "state": 0, "quantity": 1, "catalogRefId": "xsku1043" }], "totalCommerceItemCount": 1 }, "amountType": "ORDERAMOUNT" }, { "amount": 0, "relationshipType": "ORDERAMOUNT", "splitQuantity": 0, "quantity": 0, "amountRemainingType": "ORDERAMOUNTREMAINING", "splitAmount": 0, "commerceIdentifier": { "id": "o60004", "priceInfo": { "amount": 5, "total": 5, "shipping": 0, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": false, "manualAdjustmentTotal": 0, "rawSubtotal": 5, "discountAmount": 0, "adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }]

140 5 External REST MVC Service Call Examples

}, "commerceItems": [{ "id": "ci7000008", "productDisplayName": "Gift Wrap", "returnedQuantity": 0, "priceInfo": { "quantityDiscounted": 0, "quantityAsQualifier": 0, "onSale": false, "currencyCode": "USD", "orderDiscountShare": 0, "adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }], "amount": 5, "discountable": null, "rawTotalPrice": 5, "listPrice": 5, "amountIsFinal": false, "discounted": false, "salePrice": 0 }, "state": 0, "quantity": 1, "catalogRefId": "xsku1043" }], "totalCommerceItemCount": 1 }, "paymentMethod": "visa - 1111", "amountType": "ORDERAMOUNT" }]}

Applying Multiple Payment Groups to an Order

The applyMultiplePaymentGroups actor-chain is used to apply multiple payment groups to an order.

Parameter Description

listId The ID of the commerce identifier.

cipicount The number of Commerce Identifier Payment Info

(CIPI) items that are included in the request.

cipiList.amount Amount that is being applied to the payment group.

cipiList.creditCardVerificationNumber The credit card verification number.

5 External REST MVC Service Call Examples 141

Apply Multiple Payment Groups Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{ \"listId\" : \"o50002\", \"cipicount\" : \"1\", \"cipiList\" :{ \"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\":[{\"atg-rest-class-type\":\"atg.commerce.order.purchase.CommerceIdentifierPaymentInfo\", \"amount\" : \"15.00\",\"creditCardVerificationNumber\" : \"1234\"}]}}""http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/applyMultiplePaymentGroups"

Creating a New Credit Card

The CreateCreditCardActor is used to create a new credit card when working in the Billing page. The path to

this actor is: /atg/commerce/order/purchase/CreateCreditCardActor.

This actor contains the newCreditCard actor-chain:

Parameter Description

creditCardType The type of credit card to add.

creditCardNumber The credit card number.

expirationMonth The month that the credit card expires.

expirationYear The year that the credit card expires.

generateNickname Used to generate a nickname for the credit card. This parameter is always set

to true.

firstName The first name on the credit card.

middleName The middle name or initial on the credit card.

lastName The last name on the credit card.

address1 The first address field on the credit card.

address2 The second address field on the credit card.

city The city on the credit card.

state The state on the credit card.

country The country on the credit card.

postalCode The postal code on the credit card.

phoneNumber A phone number associated with the credit card.

142 5 External REST MVC Service Call Examples

Create New Credit Card Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{ \"creditCardType\": \"visa\",\"creditCardNumber\":\"4111111111111111\",\"expirationMonth\": \"1\",\"expirationYear\":\"2020\",\"firstName\": \"John\",\"lastName\": \"Doe\",\"address1\":\"1 Main St.\",\"city\": \"Cambridge\",\"state\": \"MA\",\"country\":\"USA\",\"postalCode\": \"02146\" }" "http://localhost:8280/rest/model/atg/commerce/order/purchase/CreateCreditCardActor/newCreditCard"

Updating a Credit Card

The UpdateCreditCardActor is used to edit an existing credit card. The path to this actor is: /atg/commerce/

order/purchase/UpdateCreditCardActor.

This actor contains the updateCreditCard actor-chain:

Parameter Description

nickname The nickname of the credit card to update.

creditCardType The type of credit card to update.

creditCardNumber The credit card number to update.

expirationMonth The month that the credit card expires.

expirationYear The year that the credit card expires.

firstName The first name on the credit card.

middleName The middle name or initial on the credit card.

lastName The last name on the credit card.

address1 The first address field on the credit card.

address2 The second address field on the credit card.

city The city on the credit card.

state The state on the credit card.

country The country on the credit card.

postalCode The postal code on the credit card.

phoneNumber A phone number associated with the credit card.

5 External REST MVC Service Call Examples 143

Update Credit Card Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"nickname\" : \"Visa\", \"creditCardType\" : \"Visa\", \"creditCardNumber\" :\"4111111111111111\", \"expirationMonth\" : \"06\", \"expirationYear\" : \"2017\",\"firstName\":\"Joe\", \"middleName\":\"C\", \"lastName\":\"Smith\",\"address1\":\"432 Willow Road\", \"address2\":\"NA\", \"city\":\"Broadbrook\",\"state\":\"MA\", \"country\":\"USA\", \"postalCode\":\"01234\",\"phoneNumber\":\"6176378687\" }" "http://localhost:8280/rest/model/atg/commerce/order/purchase/UpdateCreditCardActor/updateCreditCard"

Working with Catalogs

The ProductCatalogActor is used to get catalog and product information. The path to this actor is: /atg/

commerce/catalog/ProductCatalogActor.

This actor contains the following actor-chains:

Actor-Chain Description

fractionalQuantityAllowed Boolean identification that indicates if fractional quantities

are permitted with the product/SKU combination.

getCurrentCatalogRootCategories Obtains the user’s current catalog and root categories.

getCategory Displays the user’s sub-categories.

getProduct Displays a product by product ID.

getSku Displays a SKU by its ID.

outputProduct Outputs a product, including the prices for its child SKUs.

outputProductSummary Outputs product properties, as well as list and sale price

ranges.

Identifying if Fractional Quantities Are Allowed

The fractionalQuantityAllowed actor-chain indicates if fractional quantities are permitted for a product/

SKU combination. This actor-chain is Boolean and returns either true or false. It uses the following parameters:

Parameter Description

productId The ID of the product.

144 5 External REST MVC Service Call Examples

Parameter Description

skuId The ID of the SKU.

Note that when passing in URL parameters that contain quantities, you must ensure that the SKU or product

values being passed in match the quantity type. For example, if a SKU uses fractional values, the value passed in

must be a fractional value, such as 14.0. If the SKU does not use fractional values, the value passed in should be

a whole number. For additional information on working with Fractional Quantities, refer to the Core Commerce

Programming Guide.

Identify Fractional Quantities Allowed Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{ \"productId\" : \"xprod2085\", \"skuId\" : \"sku225\" }" http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/fractionalQuantityAllowed"

Getting the User’s Current Catalog

The getCurrentCatalogRootCategories actor-chain looks at the user’s profile and obtains their current

catalog and root categories.

Parameters: None

Get Current Catalog Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/getCurrentCatalogRootCategories"

A typical server response may be similar to the following:

{"rootCategories": [ { "id": "rootCategory", "description": null, "defaultParentCategory": null, "displayName": "Commerce Root", "type": null }, { "id": "NonNavigableProducts", "description": "", "defaultParentCategory": null, "displayName": "Non Navigable Products", "type": null }]}

5 External REST MVC Service Call Examples 145

Browsing the Catalog By Category ID

The getCatagory actor-chain allows the user to browse the catalog sub-categories. The actor-chain looks for

a category using its categoryId. If the category is located, the chain checks whether the category belongs to

the user’s catalog in their current profile, and if the item belongs to the current site. If it does, the chain returns

the category. If the category is not found using the catalogId, the chain will return an empty response. If the

category does not belong to a user’s catalog or current site, the chain will return an error message.

Parameter Description

categoryId The ID of the category.

filterBySite Identifies if the output is filtered by site. Set to true by default.

filterByCatalog Identifies if the output is filtered by catalog. Set to true by default.

Get Catalog By Sub-Categories Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{ \"categoryId\" : \"cat50056\" }" "http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/getCategory"

The server response might be similar to the following:

{ "childCategories": [ { "id": "cat50056", "description": null, "defaultParentCategory": null, "displayName": "Gift Shop", "type": null }, { "id": "cat50001", "description": "", "defaultParentCategory": null, "displayName": "Women", "type": null }, { "id": "catMen", "description": "", "defaultParentCategory": null, "displayName": "Men", "type": null }, { "id": "cat50097", "description": "", "defaultParentCategory": null,

146 5 External REST MVC Service Call Examples

"displayName": "Shoes", "type": null }, { "id": "cat10016", "description": null, "defaultParentCategory": null, "displayName": "Home Accents", "type": null } ], "category": { "id": "rootCategory", "description": null, "defaultParentCategory": null, "displayName": "Commerce Root", "type": null }}

Browsing the Catalog by Product ID

The getProduct actor-chain allows the user to look up products by their ID.

Parameter Description

productId The ID of the product.

catalogs Used by the CategoryItemLookupDroplet. If filterByCatalog is set to true,

this parameter provides the list of acceptable catalogs.

filterBySite Identifies if the output is filtered by site. Set to true by default.

filterByCatalog Identifies if the output is filtered by catalog. Set to true by default.

sites Used by the CategoryItemLookupDroplet. If filterBySite is set to true, this

parameter provides the list of acceptable sites.

Get Product by Product ID Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"productId\" : \"xprod2085\"}" "http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/getProduct"

The server response may be similar to the following:

{ "product": { "currencyCode": "USD",

5 External REST MVC Service Call Examples 147

"highestSalePrice": 19, "lowestSalePrice": 19, "lowestListPrice": 19, "fullImageUrl": "/crsdocroot/content/images/products/full/HOME_TumblerGlass_full.jpg", "childSKUs": [{ "listPrice": 19, "displayName": "Tumbler Glass", "type": "sku", "repositoryId": "xsku2085" }], "repositoryId": "xprod2085", "highestListPrice": 19, "description": "Tumbler glass great for mixed drinks and other beverages", "largeImageUrl": "/crsdocroot/content/images/products/large/HOME_TumblerGlass_large.jpg", "longDescription": "Our heavy glass tumblers are a versatile addition to your barware collection. Holds 12 ounces. Dishwasher safe. Made in Poland.", "isNavigableProduct": true, "mediumImageUrl": "/crsdocroot/content/images/products/medium/HOME_TumblerGlass_medium.jpg", "displayName": "Tumbler Glass", "thumbnailImageUrl": "/crsdocroot/content/images/products/thumb/HOME_TumblerGlass_thumb.jpg"}}

Browsing the Catalog by SKU ID

The getSku actor-chain allows the user to look up SKUs by their ID.

Parameter Description

skuId The ID of the SKU.

filterBySite Identifies if the output is filtered by site. Set to true by default.

Get SKU by SKU ID Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"getSku\" : \"sku1234 \"}" "http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/getSku"

Return Product Prices

The outputProduct actor-chain returns a product as well as the prices for its child SKUs. This actor-chain uses

the following parameter:

148 5 External REST MVC Service Call Examples

Parameter Description

product A product repository item.

Get Price Output Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"product\" : \"prod215\"}" "http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/outputProduct"

Return Product Summary Prices

The outputProductSummary actor-chain returns product properties, as well as list and sales price ranges

within a currency code. This actor-chain uses the following parameter:

Parameter Description

product A product repository item.

Get Price Output Summary Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"product\" : \"prod215\"}" "http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/outputProductSummary"

Getting Product Prices

The PricingActor is used to obtain prices for products using product IDs or SKU IDs. The path to this actor is: /

atg/commerce/pricing.

This actor contains the following actor-chains:

Actor-Chain Description

productPriceRanges Provides the lowest and highest sale price for a product. These

prices are obtained from the user’s profile.

skuPrices Displays either the listPrice and salePrice for a specific

SKU if price lists are enabled. If price lists are not enabled,

displays both listPrice and salePrice.

5 External REST MVC Service Call Examples 149

Getting Lowest and Highest Prices for a Product

The productPriceRanges actor-chain returns the lowest and highest prices for a specific product.

Parameter Description

productId Identifies the product ID to use.

Get Prices by Product ID Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"productId\" : \"xprod2085\"}" "http://localhost:8280/rest/model/atg/commerce/pricing/PricingActor/productPriceRanges"

The server response may be similar to the following:

{"highestSalePrice": 19, "lowestSalePrice": 19, }

Getting List Price and Sale Prices for a SKU

The skuPrices actor-chain returns the list and sale prices for a specific product using its SKU ID:

Parameter Description

productId Identifies the product ID to use. The input is used only for price list pricing. This

parameter is optional.

skuId The SKU ID to use.

Get Prices by SKU ID Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"skuId\" : \"xsku2085\"}" "http://localhost:8280/rest/model/atg/commerce/pricing/PricingActor/skuPrices"

The server response may be similar to the following:

{"listPrice": 19, "salePrice": 19,}

If you are not using price list pricing you can pass additional input parameters. This is because SKU-based pricing

uses a nested actor chain that calls into getSku in productCatalogActor.xml, which accepts the following

input parameters:

150 5 External REST MVC Service Call Examples

<input name="repositoryKey" value="${nucleus['/atg/dynamo/servlet/RequestLocale'].locale}"/><input name="id" value="${(skuId != null) ? skuId : param.skuId}"/><input name="filterBySite" value="${(filterBySite != null) ? filterBySite : param.filterBySite}" />

Working with Orders

There are a number of REST services that have been created that allow you to work with orders.

Looking Up an Order by Order ID or User ID

The OrderLookupActor is used to look up the current user’s orders by order or user ID. The path to this actor is:

/atg/commerce/order/OrderLookupActor.

This actor contains the orderLookup actor-chain:

Parameter Description

orderId Identifies the order ID to use when looking up the order.

Lookup Order By Order ID Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"orderId\" : \"o220001\"}" http://localhost:8280/rest/model/atg/commerce/order/OrderLookupActor/orderLookup

A typical server response may resemble the following:

{"result": { "id": "o120001", "priceInfo": { "amount": 109.2, "total": 109.2, "shipping": 0, "currencyCode": "USD", "tax": 0, "rawSubtotal": 119.2, "discountAmount": 10 }, "commerceItems": [{ "id": "ci11000001", "productDisplayName": "Hubbard Chair", "priceInfo": { "amount": 119.2,

5 External REST MVC Service Call Examples 151

"currencyCode": "USD", "currentPriceDetailsSorted": [{ "amount": 119.2, "currencyCode": "USD", "quantity": 1, "detailedUnitPrice": 119.2 }] }, "quantity": 1, "catalogRefId": "xsku2126", "productId": "xprod2126" }], "totalCommerceItemCount": 1}}

Cancelling or Deleting an Order

The CancelOrderActor is used to cancel or delete the current order. This actor is located in: /atg/commerce/

order/purchase/CancelOrderActor.

This actor contains the following actor-chains:

Actor-Chain Description

cancelCurrentOrder Cancels or deletes the user’s current order.

cancelOrder Cancels or deletes an order.

Cancel or Delete Current Order

The cancelCurrentOrder actor-chain deletes the current order.

Parameters: None

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CancelOrderActor/cancelCurrentOrder"

Cancel or Delete a Specific Order

The cancelOrder actor-chain deletes a specified order.

Parameter Description

orderIdToCancel Provides the ID of the order to cancel.

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d

152 5 External REST MVC Service Call Examples

"{\"orderIdToCancel\":\"o99240003\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/CancelOrderActor/cancelOrder"

Saving an Order

The SaveOrderActor saves an order. It is located in: /atg/commerce/order/purchase/

SaveOrderActor.

This actor has the saveOrder actor-chain:

Parameter Description

description A description of why the order was saved.

Save Order Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"{\"description\":\"Customer is returning later\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/SaveOrderActor"

Claiming a Coupon

The CouponActor is used to claim a coupon. It is located in: /atg/commerce/promotion/CouponActor.

This actor has the claimCoupon actor-chain:

Parameter Description

couponClaimCode The coupon code that is being claimed.

Claim Coupon Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"couponClaimCode\":\"TENSHIP\" }" "http://localhost:8280/rest/model/atg/commerce/promotion/CouponActor/claimCoupon"

Confirming an Order

The ConfirmOrderActor is used to re-price the order prior to confirming the order. The path to this actor is: /

atg/commerce/pricing/ConfirmOrderActor.

This actor contains the confirmOrder actor-chain.

5 External REST MVC Service Call Examples 153

Confirm Order Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"{ \"howMany\" : 3 } "http://localhost:8280/rest/model/atg/commerce/order/purchase/ConfirmOrderActor/confirmOrder"

The server response may be similar to the following:

{"order": { "lastModifiedTime": 1363287004602, "shippingGroupCount": 1, "paymentGroupCount": 1, "shippingGroups": [{ "specialInstructions": {}, "handlingInstructions": [], "state": 0, "locationId": null, "shippingMethod": "Ground", "id": "sg140002", "trackingNumber": null, "priceInfo": { "amount": 6.5, "currencyCode": "USD", "amountIsFinal": false, "discounted": false, "rawShipping": 6.5 }, "description": "sg140002", "actualShipDate": null, "submittedDate": null, "shipOnDate": null, "shippingAddress": { "middleName": null, "lastName": "Smith", "ownerId": null, "state": "MA", "address1": "1 Main St", "address2": "", "address3": null, "companyName": null, "suffix": null, "city": "Cambridge", "country": "USA", "id": null, "postalCode": "02046", "faxNumber": null, "phoneNumber": "6176378687", "county": null, "email": "jsmith@example.com", "prefix": null, "firstName": "John", "jobTitle": null }, "stateDetail": null }], "commerceItems": [{ "id": "ci11000001", "productDisplayName": "Hubbard Chair",

154 5 External REST MVC Service Call Examples

"returnedQuantity": 0, "priceInfo": { "amount": 119.2, "quantityDiscounted": 1, "discountable": true, "priceListId": "listPrices", "onSale": false, "rawTotalPrice": 149, "currencyCode": "USD", "amountIsFinal": false, "listPrice": 149, "discounted": true, "currentPriceDetailsSorted": [{ "amount": 119.2, "itemPriceInfo": null, "currencyCode": "USD", "tax": 0, "range": { "lowBound": 0, "class": "atg.core.util.Range", "highBound": 0, "size": 1 }, "amountIsFinal": false, "discounted": true, "quantity": 1, "detailedUnitPrice": 119.2 }], "salePrice": 0 }, "catalogId": null, "quantity": 1, "catalogRefId": "xsku2126", "catalogKey": "en_US", "productId": "xprod2126" }], "id": "o120001", "siteId": "homeSite", "taxPriceInfo": { "amount": 0, "currencyCode": "USD", "countyTax": 0, "amountIsFinal": false, "countryTax": 0, "discounted": false, "stateTax": 0, "cityTax": 0, "districtTax": 0 }, "priceInfo": { "amount": 109.2, "total": 115.7, "shipping": 6.5, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": true, "manualAdjustmentTotal": 0, "rawSubtotal": 119.2, "discountAmount": 10

5 External REST MVC Service Call Examples 155

}, "paymentGroups": [{ "amount": 0, "currencyCode": null, "expirationMonth": "1", "expirationYear": "2014", "paymentId": "pg140002", "creditCardNumber": "1111", "expirationDayOfMonth": null, "billingAddress": { "middleName": null, "lastName": "Smith", "ownerId": null, "state": "MA", "address1": "1 Main St", "address2": null, "address3": null, "companyName": null, "suffix": null, "city": "Cambridge", "country": "USA", "id": null, "postalCode": "02046", "faxNumber": null, "phoneNumber": "6176378687", "county": null, "email": "jsmith@example.com", "prefix": null, "firstName": "John", "jobTitle": null }, "creditCardType": "Visa", "orderId": null }], "profileId": "230000", "creationTime": 1363282777057, "relationships": [ { "id": "r110002", "amount": 0, "relationshipType": "SHIPPINGQUANTITY", "returnedQuantity": 0, "shippingGroupId": "sg140002", "commerceItemId": "ci11000001", "quantity": 1 }, { "amount": 0, "id": "r110004", "relationshipType": "ORDERAMOUNTREMAINING", "paymentGroupId": "pg140002", "orderId": "o120001" } ], "totalCommerceItemCount": 1}}

156 5 External REST MVC Service Call Examples

Committing an Order

The CommitOrderActor is used to commit the order. The path to this actor is: /atg/commerce/order/

purchase/CommitOrderActor.

This actor contains the commitOrder actor-chain.

Parameter Description

allowEmptyOrders If set to false, will return an error if an order is commited that contains no

items.

salesChannel The sales channel used to submit the order. The values are “Web”, “Call

Center” or Scheduled Orders”, and are defined in the Order repository.

siteId The ID of the site to be recorded in the order.

Commit Order Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CommitOrderActor/commitOrder"

Sending Order Confirmation

The OrderConfirmationActor is referenced by the CommitOrderActor to display confirmation of a

successfully committed order. The path to this actor is/atg/commerce/order/purchase/

OrderConfirmationActor.

This actor contains the orderConfirmation actor-chain.

Parameters: None

Confirm Order Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/OrderConfirmationActor/orderConfirmation"

The server response may be similar to the following:

{orderId: "0132", email: jsmith@example.com}

Obtaining Closeness Qualifiers

The ClosenessQualifierActor enables a customer to see how close their order is to qualifying for a

promotion. This actor is located at /atg/commerce/custsvc/promotion/

5 External REST MVC Service Call Examples 157

ClosenessQualifierActor, and contains the getClosenessQualifiers actor-chain.

Parameters: None

Obtain Closeness Qualifiers Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/promotion/ClosenessQualifierActor/getClosenessQualifiers"

Working with Returns and Exchanges

The returns and exchanges process allows a customer to return or exchange an item. For a overview of the

process, refer to the Returns and Exchange Process Overview (page 293) section in the Internal REST MVC

Service Call Examples (page 179) section.

The ReturnsActor is used to initiate, confirm and cancel returns. The path to this actor is: /atg/commerce/

custsvc/returns/ReturnsActor.

This actor contains the following actor-chains:

Actor-Chain Description

createReturn Initiates a return request.

selectItems Identifies the items to add to the return request.

returnReasons Retrieves possible reasons for the return of an item.

confirmReturn Confirms the return request.

confirmation Displays return details to confirm successful return.

cancelReturnRequest Cancels the return request.

applyRefunds Applies non-default refund values to the order’s refund

method types.

modifiableRefundsMethodList Retrieves a list of refund method types.

isCurrentOrderReturnable Identifies if the current order is returnable.

isReturnActive Determines if there is a return in process for this order.

returnsHistory Displays return history for this order.

returns Displays the order’s return request.

nonReturnItemDetails Displays refund adjustments that were applied to non-return

items. This chain supports fractional quantities.

158 5 External REST MVC Service Call Examples

Initiating a Return

The createReturn actor-chain initiates and creates a return request. Note that this actor-chain calls

the ReturnFormHandler, as opposed to the internal createReturn actor-chain, which calls the

StartReturnExchangeProcess form handler. For information on the internal createReturns actor-chain,

refer to the Creating a Return (page 295) section. This actor-chain contains the following parameter:

Parameter Description

newOrderId The ID of the order to be returned.

Initiate Returns Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"{\"newOrderId\":\"o2620001\"}" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/ReturnsActor/createReturn"

Selecting Items to Return

The selectItems actor-chain identifies the items that will be returned in the current return request. This actor-

chain takes the input from an updated JSON-formatted return request and then uses that input to set the server-

side shipping group list’s return item values. Note that you must update the shippingGroupList items to set

the number of items to be returned or exchanged, and the reason code. Refer to the Obtaining Return Reason

Codes section for information on retrieving reason codes.

This actor-chain contains the following parameters:

Parameter Description

processName Identifies if the process is a return or an exchange.

jsonReturnRequest Identifies the updated Jason-formatted return request

where the item to be returned or exchanged in the

shippingGroupList.itemList has been updated

so that either the quantityToReturn property or the

quantityToExchange property is greater than 0, and the

returnReasoncode is set.

Add Items to Return Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{\"processName\":\"Return\",\"jsonReturnRequest\":{\"returnRequest\":{\"shippingGroupList\":[{\"itemList\":[{\"id\":\"xcr10101\",\"shippingGroupId\":\"xcsg20080\",\"quantityToReturn\":1,\"returnReason\":\"didNotLike\",\"quantityToExchange\":0},{\"id\":\"xcr10102\",\"shippingGroupId\":\"xcsg20080\",

5 External REST MVC Service Call Examples 159

\"quantityToReturn\":1,\"returnReason\":\"defective\",\"quantityToExchange\":0}]}]}}}" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/selectItems"

The following is an XML-based example:

curl -L -v -b customer_cookies.txt -H "Content-Type: application/xml" –d"<parameters><jsonReturnRequest>{"returnRequest":{"shippingGroupList":[{"itemList":[{"id":"xcr10101","shippingGroupId":"xcsg20080","quantityToReturn":1,"returnReason":"didNotLike","quantityToExchange":0},{"id":"xcr10102","shippingGroupId":"xcsg20080","quantityToReturn":1,"returnReason":"defective","quantityToExchange":0}]}]}}</jsonReturnRequest><processName>Return</processName></parameters>" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/selectItems"

The server response may be similar to the following:

{ "returnRequest":{ "returnPaymentState":"Refund", "otherRefund":0, "requestId":null, "state":"incomplete", "processName":"Return", "actualShippingRefund":12.62, "replacementOrderId":null, "originatingOrderId":"xco30045", "exchangeProcess":false, "returnAdjustedOrderId":"o350068", "orderCurrencyCode":"USD", "refundMethodList":[ { "refundType":"creditCard", "amount":113.62, "maximumRefundAmount":131.85 }, { "refundType":"storeCredit", "amount":0, "maximumRefundAmount":-1 } ], "returnItemCount":2, "actualTaxRefund":0, "returnItemList":[ { "quantityToExchange":0, "suggestedTaxRefundShare":0, "quantityReceived":0, "itemCurrencyCode":"USD", "returnItemId":"xcr10101", "actualTaxRefundShare":0, "refundAmount":50.52, "shippingGroupId":"xcsg20080", "quantityReturned":0, "quantityShipped":1, "quantityAvailable":1,

160 5 External REST MVC Service Call Examples

"description":"Boyfriend Jeans", "quantityToReturn":1, "actualShippingRefundShare":6.31, "suggestedShippingRefundShare":6.31, "commerceItemId":"xci1000051", "catalogRefId":"xsku2519_2", "suggestedRefundAmount":50.52, "disposition":null, "returnReason":"didNotLike" }, { "quantityToExchange":0, "suggestedTaxRefundShare":0, "quantityReceived":0, "itemCurrencyCode":"USD", "returnItemId":"xcr10102", "actualTaxRefundShare":0, "refundAmount":51.44, "shippingGroupId":"xcsg20080", "quantityReturned":0, "quantityShipped":1, "quantityAvailable":1, "description":"Corduroy Cargo Pants", "quantityToReturn":1, "actualShippingRefundShare":6.31, "suggestedShippingRefundShare":6.31, "commerceItemId":"xci1000052", "catalogRefId":"xsku2512_2", "suggestedRefundAmount":51.44, "disposition":null, "returnReason":"defective" } ], "processImmediately":false, "rma":null, "returnFee":0, "orderId":"xco30045", "profile":{ "middleName":null, "lastName":"Smith", "id":"se-570085", "login":"jsmith@example.com", "firstName":"Joe" } }}

Getting Return Reason Codes

The returnReasons actor-chain displays a list of all reason codes. Reason codes can be used in the

selectItems actor-chain as outlined in Selecting Items to Return (page 158).

Parameters: None

Obtain Return Reason Codes Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"

5 External REST MVC Service Call Examples 161

"http://localhost:8181/rest/model/atg/commerce/custsvc/returns/ReturnsActor/returnReasons"

The server may return a response similar to the following:

{ "reasons": { "incorrectSize": "Incorrect Size", "incorrectColor": "Incorrect Color", "didNotMeetExpectations": "Did Not Meet Expectations", "didNotLike": "Did Not Like", "defective": "Defective", "incorrectItem": "IncorrectItem" }}

Confirming a Return

The confirmReturn actor-chain submits and processes a return request, and displays confirmation detail if a

submission is successful.

Parameters: None

Confirm a Return Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8181/rest/model/atg/commerce/custsvc/returns/ReturnsActor/confirmReturn"

Displaying Return Confirmation Details

The confirmation is an informational actor-chain used to display return details confirming that the return was

successful. You can use this actor-chain to display return data as part of the confirmReturn actor-chain output.

This actor-chain outputs the confirmation e-mail address. To display other information, such as the exchange

order ID, you must customize this call to hold a reference to the return request. Refer to the ATG Platform API

Reference for information on customizing this actor-chain.

Note that this actor is invoked by the confirmReturn actor-chain. Calling this actor directly will display no

results.

Canceling a Return

The cancelReturnRequest actor-chain cancels the return request at any point during the returns process.

Parameters: None

Cancel a Return Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"

162 5 External REST MVC Service Call Examples

"http://localhost:8181/rest/model/atg/commerce/custsvc/returns/ReturnsActor/cancelReturnRequest"

Returning Refund Methods

The modifiableRefundsMethodList actor-chain retrieves the list of all credit and payment methods to which

a refund can be applied, and the default values for the item to be returned. Note that this call should be run after

running the selectItems actor-chain.

Parameters: None

Refund Methods Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"http://localhost:8180/rest/model/atg/commerce/custsvc/returns/ReturnsActor/modifiableRefundsMethodList"

The server response may be similar to the following:

{ "modifiableRefundMethodList": [{ "refundType": "creditCard", "amount": 51.31 }]}

Applying Non-Default Refund Values

The applyRefunds actor-chain is used to apply a non-default refund type and value to the order.

Parameter Description

returnMethodListSize The array size to retrieve from the JSP. The array size corresponds to the

number of refund methods available.

Non-Default Refund Values Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{\"items\":{\"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\":[{\"atg-rest-class-type\":\"atg.commerce.csr.returns.RefundMethod\", \"refundType\":\"creditCard\",\"amount\":\"46.31\"}, {\"atg-rest-class-type\":\"atg.commerce.csr.returns.RefundMethod\", \"refundType\":\"storeCredit\",\"amount\":\"5.00\"}]}, \"returnMethodListSize\" : \"2\"}""http://localhost:8180/rest/model/atg/commerce/custsvc/returns/ReturnsActor/

5 External REST MVC Service Call Examples 163

applyRefunds"

Identifying Returnable Orders

The isCurrentOrderReturnable actor chain looks at the current order to see if it is a returnable order. It

provides a true or false server response.

Parameters: None

Is Order Returnable Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/order/ReturnsActor/isCurrentOrderReturnable"

Viewing Details of Returned Items

The returns actor-chain provides details of returned items in the current order.

Parameter Description

orderId The ID of the order.

Does Order Contain Active Return Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{\"orderId\" : \"xco30049\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/returns/ReturnsActor/returns"

Reviewing Return History

The returnsHistory actor-chain is used to view returns history.

Parameter Description

orderId The ID of the order to be returned.

Returns History Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d

164 5 External REST MVC Service Call Examples

"{\"orderId\":\"o2620001\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/returns/ReturnsActor/returnsHistory"

Showing Non-Return Items

The nonReturnItemDetails actor-chain displays any non-returned items that have been affected by the

return. When working on a current working order, when a return is completed, the system displays the refund

details with non-returnable items, as well as the refund types and any additional notes. The return is then

submitted for completion. Note that this call will produce information only after selectItems is called, and if

the items being returned affect non-returned items.

Parameters: None

Complete Return Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"http://localhost:8180/rest/model/atg/commerce/custsvc/returns/ReturnsActor/nonReturnItemDetails"

Identifying if an Order is Part of an Active Return

The isReturnActive actor-chain looks at the current order to see if it is associated with an active return. It

provides a true or false server response.

Parameters: None

Is Order Part of an Active Return Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/order/ReturnsActor/isReturnActive"

Updating Credit Cards for a Returns

The UpdateCreditCardActor is used to edit an existing credit card for a return. The path to this actor is: /atg/

commerce/order/purchase/UpdateCreditCardActor.

This actor contains the updateCreditCardForReturns actor-chain. This actor-chain depends on the

ReturnsActor createReturn actor-chain to obtain the correct information.

Parameter Description

creditCardType The type of credit card.

creditCardNumber The credit card number.

5 External REST MVC Service Call Examples 165

Parameter Description

expirationMonth The month that the credit card expires.

expirationYear The year that the credit card expires.

firstName The first name on the credit card.

middleName The middle name or initial on the credit card.

lastName The last name on the credit card.

address1 The first address field on the credit card.

address2 The second address field on the credit card.

city The city on the credit card.

state The state on the credit card.

country The country on the credit card.

postalCode The postal code on the credit card.

phoneNumber A phone number associated with the credit card.

Update Credit Card Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"{\"paymentGroupId\":\"pg3980014\",\"creditCardType\":\"visa\",\"creditCardNumber\": \"4111111111111111\",\"expirationMonth\":\"1\",\"expirationYear\": \"2017\"}" "http://localhost:8181/rest/model/atg/commerce/custsvc/order/UpdateCreditCardActor/updateCreditCardForReturns"

Displaying Lost Promotions

The LostPromotionsActor displays a list of promotions that a customer loses during the return or exchange

process. Note that this data is not saved and can only be displayed during the return and exchange process.

This actor is located at /atg/commerce/custsvc/returns/lostPromotionsActor. It contains the

promotionsLost actor-chain.

Parameters: None

Display Lost Promotions Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/returns/LostPromotionsActor/promotionsLost"

The response may be similar to the following:

166 5 External REST MVC Service Call Examples

{"promotionsLost":"promo50012"}

Working with Gift Lists

The following actors are used with gift lists. For adding items to a cart, see Add Item From Wish List

Example (page 127) and Add Item From Gift List Example (page 127).

The GiftlistActor contains several actor-chains that initiate gift list actions. The path for this actor is /atg/

commerce/gifts/GiftlistActor.

This actor contains the following actor-chains:

Actor-Chain Description

createGiftlist Creates a gift list.

updateGiftlist Updates a gift list.

addItemToGiflList Adds an item to a gift list. Supports fractional quantities.

removeItemFromGiftlist Removes an item from a gift list.

addItemToWishlist Adds an item to a wish list. Supports fractional quantities.

removeItemFromWishlist Removes an item from a wish list.

moveItemsFromCart Removes a gift or wish list item from the Shopping Cart. Supports

fractional quantities.

deleteGiftlist Deletes a gift list.

profileGiftlists Views the current profile’s list of gift lists.

Creating a Gift List

The createGiftlist actor-chain creates a gift list.

Parameter Description

isPublished Identifies if the list has been published.

eventName The name of the gift list event.

eventDate The date of the gift list event.

5 External REST MVC Service Call Examples 167

Parameter Description

eventType The type of the gift list event.

description A description of the gift list.

comments Any comments that are included with the list.

shippingAddressId The ID of the shipping address.

instructions Any instructions that are included with the list.

Create Gift List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d"{\"eventName\" : \"Birthday\", \"eventType\" : \"Birthday\", "eventDate" :\"AUG 30, 2013\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/createGiftlist"

Updating a Gift List

The updateGiftlist actor-chain edits a gift list.

Parameter Description

giftlistId The ID of the gift list.

isPublished Identifies if the list is published.

eventName The name of the gift list event.

eventDate The date of the gift list event.

eventType The type of the gift list event.

description A description associated with the list.

shippingAddressId The Shipping Address ID associated with the list.

instructions Any instructions that are associated with the list.

Update Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl20002\", \"eventName\" : \"updated Birthday\", \"eventType\" :\"Birthday\", \"eventDate\" : \"AUG 30, 2013\"}" "http://localhost:8280/rest/

168 5 External REST MVC Service Call Examples

model/atg/commerce/gifts/GiftlistActor/updateGiftlist"

Adding Items to a Gift List

The addItemToGiftlist actor-chain adds an item to a gift list.

Parameter Description

giftlistId The ID of the gift list.

quantity The quantity of the products to add to the gift list.

productId The product ID of the product to add to the gift list.

catalogRefIds The catalog reference ID of the product being added to the gift list.

Add Item to Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl230009\", \"productId\": \"xprod1015\", \"catalogRefIds\" :\"xsku1043\", \"quantity\": \"2\" }" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/addItemToGiftlist"

Adding Items to a Wish List

The addItemToWishlist actor-chain adds an item to a wish list.

Parameter Description

quantity The quantity of the products to add to the wish list.

productId The product ID of the product to add to the wish list.

catalogRefIds The catalog reference ID of the product being added to the wish list.

Add Item to Wish List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"productId\": \"prod10004\", \"catalogRefIds\" : \"sku30029\", \"quantity\":\"2\" }" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/addItemToWishlist"

5 External REST MVC Service Call Examples 169

Removing Items from a Gift List

The removeItemFromGiftlist actor-chain removes an item from a gift list.

Parameter Description

giftlistId The ID of the gift list from which the items will be removed.

removeGiftitemIds The ID of the items to remove from the gift list.

Remove Item from Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl20002\", \"removeGiftitemIds\": \"gi10001\" }""http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/removeItemFromGiftlist"

Removing Items from a Wish List

The removeItemFromWishlist actor-chain removes an item from a wish list.

Parameter Description

removeGiftitemIds The ID of the items to be reomved from the gift list.

Remove Item from Wish List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"removeGiftitemIds\": \"gi20001\" }" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/removeItemFromWishlist"

Moving Items to a Gift or Wish List from a Shopping Cart

The moveItemsFromCart actor-chain takes an item from a shopping cart and moves it into the specified gift or

wish list. You can specify a default quantity for an item, or specify the quantity for a specific item.

Parameter Description

giftlistId The ID of the gift or wish list to which the items will be moved.

itemIds The IDs of the items to move to the list.

170 5 External REST MVC Service Call Examples

Parameter Description

quantity The quantity of the items to move to the list.

Move Item to Gift or Wish List from Cart Example

The following example shows how you would specify the default quantity for the items within the cart:

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl20002\", \"itemIds\": \"ci10000003\", \"quantity\": 1}""http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/moveItemsFromCart"

The following example shows how you would specify the quantity for a particular item within the cart:

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl20002\", \"itemIds\": \"ci10000003\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/moveItemsFromCart?ci10000003=1"

Deleting a Gift List

The deleteGiftlist actor-chain deletes a specific gift.

Parameter Description

giftlistId The ID of the gift list to delete.

Delete a Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl20002\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/deleteGiftlist"

Viewing the Current Profile’s List of Gift Lists

The profileGiftlist actor-chain views the current profile’s list of gift lists.

Parameters: None

View Current Profile’s List of Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/profileGiftlists"

5 External REST MVC Service Call Examples 171

The server response may be similar to the following:

{"giftlists": [ { "name": "Birthday", "repositoryId": "xgl20004" }, { "name": "Anniversary", "repositoryId": "gl430003" }]}

Viewing a Gift List

The GiftlistLookupActor is used to view a customer’s gift list. This actor is located at: /atg/commerce/

gifts/GiftlistLookupActor, and contains the info actor-chain.

Parameter Description

giftlistId The ID of the gift list to view.

View Gift List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\" : \"gl430003\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/info"

The server response may be similar to the following:

{"giftlist": { "giftlistItems": [], "instructions": "", "description": "Upcoming birthday gifts.", "name": "Birthday", "public": true, "date": {"time": 1386521853000}, "type": "Birthday", "repositoryId": "xgl20004", "addressId": "se-980030"}

Viewing a Gift List’s Items

The GiftlistLookupActor is used to view the items within a customer’s gift list. This actor is located at: /atg/

commerce/gifts/GiftlistLookupActor, and contains the items actor-chain.

172 5 External REST MVC Service Call Examples

Parameter Description

giftlistId The ID of the gift list to view.

View Gift List Item Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\" : \"gl430003\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/items?giftlistId=xgl10002"

The server response may be similar to the following:

{"giftlistItems":[ { "repositoryId":"xgi10001", "productId":"xprod1001", "siteId":"storeSiteUS", "skuId":"xsku1003", "quantity":1 }, { "repositoryId":"xgi10002", "productId":"xprod1007", "siteId":"storeSiteUS", "skuId":"xsku1026", "quantity":1 }, { "repositoryId":"xgi10003", "productId":"xprod1014", "siteId":"storeSiteUS", "skuId":"xsku1042", "quantity":1 }, { "repositoryId":"xgi10004", "productId":"xprod1047", "siteId":"storeSiteUS", "skuId":"xsku1244", "quantity":1 }, { "repositoryId":"xgi10005", "productId":"xprod2032", "siteId":"storeSiteUS", "skuId":"xsku2032", "quantity":1 }, { "repositoryId":"xgi10006", "productId":"xprod2071", "siteId":"homeSite", "skuId":"xsku2071", "quantity":1 },

5 External REST MVC Service Call Examples 173

{ "repositoryId":"xgi10007", "productId":"xprod2116", "siteId":"homeSite", "skuId":"xsku2116", "quantity":1 }, { "repositoryId":"xgi10008", "productId":"xprod2138", "siteId":"homeSite", "skuId":"xsku2138", "quantity":1 }]}

Viewing a Wish List

The GiftlistLookupActor is used to view a customer’s wish list. This actor is located at: /atg/commerce/

gifts/GiftlistLookupActor, and contains the viewWishlist actor-chain.

Parameters: None

View Wish List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/viewWishlist"

The server response may be similar to the following:

{"giftlistItems":[ { "repositoryId":"xgi10001", "productId":"xprod1001", "siteId":"storeSiteUS", "skuId":"xsku1003", "quantity":1 }, { "repositoryId":"xgi10002", "productId":"xprod1007", "siteId":"storeSiteUS", "skuId":"xsku1026", "quantity":1 }, { "repositoryId":"xgi10003", "productId":"xprod1014", "siteId":"storeSiteUS", "skuId":"xsku1042", "quantity":1 }, {

174 5 External REST MVC Service Call Examples

"repositoryId":"xgi10004", "productId":"xprod1047", "siteId":"storeSiteUS", "skuId":"xsku1244", "quantity":1 }, { "repositoryId":"xgi10005", "productId":"xprod2032", "siteId":"storeSiteUS", "skuId":"xsku2032", "quantity":1 }, { "repositoryId":"xgi10006", "productId":"xprod2071", "siteId":"homeSite", "skuId":"xsku2071", "quantity":1 }, { "repositoryId":"xgi10007", "productId":"xprod2116", "siteId":"homeSite", "skuId":"xsku2116", "quantity":1 }, { "repositoryId":"xgi10008", "productId":"xprod2138", "siteId":"homeSite", "skuId":"xsku2138", "quantity":1 }]}

Searching for a Gift List

The GiftlistSearchActor is used to find a customer’s gift list. This actor is located at: /atg/commerce/

gifts/GiftlistSearchActor, and contains the search actor-chain.

Parameter Description

currentPage Sets the current page.

searchInput Looks for matching strings in owner.firstName or owner.lastName.

firstName The first name of the customer.

lastName The last name of the customer.

eventType The list event type.

eventDate The list event date.

5 External REST MVC Service Call Examples 175

Parameter Description

resultsPerPage Sets the number of results to display per page.

state The state or province of the billing address.

Search for Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"firstName\" : \"Stuart\", \"lastName\" : \"Schmidt\", \"eventType\": \"Other\",\"eventDate\" : \"AUG 30, 2013\"} "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistSearchActor/search"

The server response may be similar to the following:

{"giftlists": [ { "giftlistItems": [], "instructions": null, "description": null, "name": "Birthday", "public": true, "date": {"time": 1377837000000}, "type": "Other", "repositoryId": "gl140010", "addressId": null }, { "giftlistItems": [{ "siteId": "storeSiteUS", "skuId": "xsku1043", "quantity": 2, "repositoryId": "gi50001", "productId": "xprod1015" }], "instructions": null, "description": null, "name": "updated test", "public": true, "date": {"time": 1377837000000}, "type": "Other", "repositoryId": "gl120010", "addressId": null }, { "giftlistItems": [], "instructions": null, "description": null, "name": "Anniversary", "public": true, "date": {"time": 1377837000000}, "type": "Other", "repositoryId": "gl120011", "addressId": null }

176 5 External REST MVC Service Call Examples

]}

Working with In-Store Pickup

The StoreLocatorActor contains two actor-chains that are used for in-store pickup. The path for this actor is /

atg/commerce/locations/StoreLocatorActor. For information on adding an item to the shopping cart for

in-store pickup, refer to the Add Item to In-Store Pickup Example (page 126).

This actor contains the following actor-chains:

Actor-Chain Description

locateItems Used for searching for an item within stores.

currentResultPageNum Used to display search result paging.

Searching for a Store

The locateItems actor-chain is used to find stores that have the specified item.

Parameter Description

skuId The SKU ID of the item to find in the store.

countryCode Used to specify a country.

state Used to specify a state.

city Used to specify a city.

postalCode Used to specify a postal code.

distance Used to identify a distance (in meters).

maxResultsPerPage The maximum number of results to display on the page.

Search for Store Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"distance\" : \"10\", \"skuId\" : \"sku30029\"}" "http://localhost:8280/rest/model/atg/commerce/locations/StoreLocatorActor/locateItems"

5 External REST MVC Service Call Examples 177

The server response may be similar to the following:

{ "FashionIsland": { "distance": 0, "postalCode": "92660", "phoneNumber": "555-555-2006", "name": "Fashion Island", "state": "CA", "address1": "401 Newport Center Drive", "stockLevel": 0, "city": "Newport", "country": "USA" }, "BiltmoreFashionPark": { "distance": 0, "postalCode": "85016", "phoneNumber": "(555) 555-1963", "name": "Biltmore Fashion Park", "state": "AZ", "address1": "2404 East Camelback Road", "stockLevel": 0, "city": "Phoenix", "country": "USA" }}

Displaying Search Results for In-Store Pickup

The currentResultPageNum actor-chain is used to display stores that contain the specified item.

Parameter Description

pageNum Identifies which page of the results set is being viewed. The default value

is 1, with the base value of this parameter set to1 instead of 0 for usability.

maxResultsPerPage The maximum number of results to display on the page.

Display In-Store Search Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"pageNum\":\"2\", \"maxResultsPerPage\":\"2\" }" "http://localhost:8280/rest/model/atg/commerce/locations/StoreLocatorActor/currentResultPageNum"

Identifying a State

The StateListActor is used to identify the state of a user’s profile locale. The path of this actor is /atg/

commerce/util, and it contains the states actor-chain.

178 5 External REST MVC Service Call Examples

Parameter Description

countryCode Identifies the country code of a specific customer.

State Identification Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"countryCode\":\"US\" }" "http://localhost:8280/rest/model/atg/commerce/util/StateListActor/states"

The server response may be similar to the following:

{"states":[ { "code":"AK", "displayName":"AK - Alaska" }, { "code":"AL", "displayName":"AL - Alabama" }, { "code":"AR", "displayName":"AR - Arkansas" },

...

}]}

6 Internal REST MVC Service Call Examples 179

6 Internal REST MVC Service Call

Examples

The following REST MVC services enable Call Center agents to assist customers. The following REST MVC calls

examples are specific to internal users, such as those used by Oracle Commerce Service Center, and are intended

for the creation of REST MVC calls for Commerce Service Center Call Center agent actions.

As described in previous sections, REST MVC calls are based on actors that perform specific functions. This

section is organized by tasks that agents perform on behalf of customers. These agent-specific REST MVC calls

are different than external user REST MVC calls in that they use the agent_cookies.txt file to store cookie

information, and are located in the DCS-CSR modules. For REST MVC calls for external customers, refer to the

External REST MVC Service Call Examples (page 115) section.

Internal REST MVC Service Calls Workflow Example

The following diagram shows an example of an agent’s workflow when adding an item to a cart. Each of the

REST MVC calls performs an action that propels the agent through the workflow. Note that depending on the

actions required, the process may flow differently.

180 6 Internal REST MVC Service Call Examples

This example begins with the agent logging in to the REST server, and ends when the customer is sent an order

confirmation e-mail.

Note: The following examples are provided as guidelines for working with Internal REST MVC calls. The

responses returned by your server may vary based upon your environment’s configuration.

Getting the Session Confirmation Number

The first actor that must be invoked is the Dynamo Session Confirmation actor. As described in the Using

Dynamo Session Confirmation Numbers (page 70) section, the session confirmation number is used by

the REST Web Services to provide secure access to the REST calls. The Form Element (page 84) and The

Component Element (page 77) use _dynSessConf for method calls and setting property values. The

SessionConfirmationActor returns the session confirmation number. The path to this actor is /atg/rest

and it uses the getSessionConfirmationNumber actor-chain.

Parameters: None

Session Confirmation Number Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/rest/SessionConfirmationActor/getSessionConfirmationNumber"

The server response may be similar to the following:

{"sessionConfirmationNumber":-5166444348429687167}

6 Internal REST MVC Service Call Examples 181

Logging Agents In and Out

The AgentProfileActor is located at /atg/agent/userprofiling/ and contains the following actor-

chains:

Actor-Chain Description

login Allows an agent to log into the site.

logout Allows an agent to log out of a site.

Logging In Agents

The login actor-chain is used to log the agent into the site and verify the appropriate login and password

credentials.

Parameter Description

login The login of the agent.

password The agent’s password.

Agent Log In Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"-d "{ \"login\" : \"ServiceAdmin\" , \"password\" : \"service123\" }""http://localhost:8280/rest/model/atg/agent/userprofiling/AgentProfileActor/login"

If the log in information proves to be correct, the following success server response occurs:

{"userId": "svcUserAdmin>}

If the log in information proved to be incorrect, the following exception would occur:

{"formError": true, "formExceptions":[{"localizedMessage":"The password and logincombination is incorrect.","errorCode":"invalidPassword"}]}

Logging Out Agents

The logout actor-chain is used to log the agent out of the site.

Parameters: None

182 6 Internal REST MVC Service Call Examples

Agent Log Out Example

curl -L -v -c agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/agent/userprofiling/AgentProfileActor/logout"

Confirming Log Out

The ConfirmLogoutActor, which uses the confirmLogout actor-chain, allows you to check confirmation

before logging the agent out. This actor is located at /atg/svc/ui/

formhandlers/ConfirmLogoutActor.

Parameter Description

TryLogout When set to true, performs a confirmation before logging the

agent out.

Confirm Logout Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"-d "{ \"TryLogout\": \"true\" }" "http://localhost:8181/rest/model/atg/svc/ui/formhandlers/ConfirmLogoutActor/confirmLogout"

Changing Agents Passwords

The ChangePasswordActor, which uses the changePassword actor-chain, is used to change the password of

the agent. This actor is located at /atg/svc/ui/formhandlers/ChangePasswordActor.

Parameter Description

newPassword The new password of the agent.

oldPassword The agent’s old password.

confirmPassword Confirmation of the new password to be set for the agent.

Change Agent Password Example

curl -L -v -c agent_cookies.txt -H "Content-Type: application/json" -d"{ \"oldPassword\" : \"passwordOne\" , \"newPassword\" : \"passwordTwo\",\"confirmPassword\" : \"passwordTwo\" }" "http://localhost:8181/rest/model/atg/svc/ui/formhandlers/ChangePasswordActor/changePassword"

6 Internal REST MVC Service Call Examples 183

Setting Default Login Page

You can set the default page the agent will access when logging in. The DefaultLoginPageActor, which uses

the defaultLoginOption actor-chain, allows you to set the default login page. The actor is located at /atg/

svc/ui/formhandlers/DefaultLoginPageActor.

Parameter Description

agentUserDefaultHomeTab The default login page for the agent.

Set Default Login Page Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"-d "{ \"agentUserDefaultHomeTab\": \"ticketsTab\" }" "http://localhost:8181/rest/model/atg/svc/ui/formhandlers/DefaultLoginPageActor/defaultLoginOption"

Restoring Defaults

You can restore the defaults for agent preferences using the RestoreDefaultAgentOptionsActor,

which uses the restoreDefaults actor-chain. The actor is located at /atg/svc/ui/formhandlers/

RestoreDefaultAgentOptionsActor.

Parameters: None

Restore Agent Preferences Options Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8181/rest/model/atg/svc/ui/formhandlers/RestoreDefaultAgentOptionsActor/restoreDefaults"

Working with Calls

The following actors are used to make calls, end calls, and add call notes.

Starting a Call

The /atg/svc/agent/ui/formhandlers/StartNewCallActor contains the startNewCall actor-chain,

which is used to initiate a new call in Commerce Service Center:

184 6 Internal REST MVC Service Call Examples

Parameter Description

doWarnings Determines if ticket disposition warnings will be generated for

changes.

doTicketDispositionPrompt Determines if ticket disposition prompts will be generated for

changes.

dispositionOption The ticket disposition option to use.

reasonCode The reason code for the ticket.

ticketNote Creates a note stored in the ticket.

publicNote Makes the note available for public viewing.

Start Call Example

This example confirms the ticket disposition settings when starting a call.

curl -L -v -b agent_cookies.txt -d "{ \"doWarnings\":true,\"doTicketDispositionPrompt\":true, \"dispositionOption\":\"save\" }""http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/StartNewCallActor/startNewCall"

The server response confirmation warning may be similar to the following:

{ "isDiscardable": true, "allWarnings": ["The current working order has items in it and has not been saved. If you continue, the order will be lost."], "activeTicketDisposition": true}

This example shows how changes are made in the ticket disposition settings when starting a call.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"doWarnings\":false, \"doTicketDispositionPrompt\":false, \"ticketNote"\:\"Junk mail\",\"reasonCode\":\"spam\", \"dispositionOption\":\"close\" }""http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/StartNewCallActor/startNewCall"

Ending a Call

The /atg/svc/agent/ui/formhandlers/EndCallActor contains the endCall actor-chain, which is used to

end a call in Commerce Service Center:

6 Internal REST MVC Service Call Examples 185

Parameter Description

doWarnings Determines if ticket disposition warnings will be generated for

changes.

doTicketDispositionPrompt Determines if ticket disposition prompts will be generated for

changes.

dispositionOption Provides the ticket disposition option to use.

reasonCode The reason code for the ticket.

ticketNote Creates a note stored in the ticket.

publicNote Makes the note available for public viewing.

End Call Example

This example confirms the ticket disposition settings when ending a call.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"doWarnings\":true, \"doTicketDispositionPrompt\":true, \"dispositionOption\":\"save\" }" "http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/EndCallActor/endCall"

The server response confirmation warning may be similar to the following:

{ "isDiscardable": true, "allWarnings": ["The current working order has items in it and has not been saved. If you continue, the order will be lost."], "activeTicketDisposition": true}

This example shows how changes are made in the ticket disposition settings when ending a call.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"doWarnings\":false, \"doTicketDispositionPrompt\":false, \"ticketNote\":\"Junk mail\",\"reasonCode\":\"spam\", \"dispositionOption\":\"close\" }""http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/EndCallActor/endCall"

Adding a Call Note

The /atg/svc/ui/formhandlers/TicketingActor contains the addNote actor-chain, which is used to add

a call note to a ticket in Commerce Service Center:

186 6 Internal REST MVC Service Call Examples

Parameter Description

noteText The text of the note.

share Identifies if the note should be shared with the customer.

inbound Marks the note as either being “inbound”, which is a note that was initiated by

the customer, or “outbound”, which is a note initiated by the agent.

noteType The type of note, which, in this case, is call.

Add Call Note Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"noteType"\ : \"call\", \"noteText\" : \"The user would like to be notified ifwe get more inventory in for this product.\", \"share\": \"false\", \"inbound\":\"true\" }" "http://localhost:8180/rest/model/atg/svc/ui/formhandlers/TicketingActor/addNote"

Working with Tickets

The TicketActor allows an agent to work with a specific ticket. This actor is located at /atg/svc/agent/ui/

formhandlers/TicketActor.

Note: The TicketActor is different than the TicketingActor. Refer to the Adding a Call Note (page 185)

example for information on the TicketingActor.

The TicketActor contains the following actor-chains:

Actor-Chain Description

workTicket Used by an agent to access a specific ticket.

createNewTicket Used to create a new ticket.

saveTicket Saves the current ticket.

associateTicket Associates a ticket.

escalateTicket Escalates a ticket.

closeTicket Closes a ticket.

releaseTicket Releases the ticket.

deferTicket Allows an agent to defer a ticket.

6 Internal REST MVC Service Call Examples 187

Actor-Chain Description

reassignTicket Allows the agent to reassign a ticket.

sendToGroup Enables an agent to send a ticket to a predefined group.

closeAsDuplicate Closes a ticket as a duplicate ticket.

beginEdit Allows an agent to begin editing a ticket.

endEdit Completes the editing of a ticket.

viewActiveTicket Provides a list of all active tickets.

Selecting a Ticket to Work On

The workTicket actor-chain, allows an agent to specify a ticket to work on.

Parameter Description

ticketId The ID of the ticket to work on.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Provides a ticket disposition option.

reasonCode Provides a ticket disposition reason code.

ticketNote Provides a note associated with the ticket.

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Select a Ticket Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{ \"ticketId\":\"2203\"}""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/workTicket"

Creating a New Ticket

The createNewTicket actor-chain allows an agent to create a new ticket, making it the current ticket.

188 6 Internal REST MVC Service Call Examples

Parameter Description

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

subStatus Provides a sub-status for the ticket.

publicNote Identifies if the ticket note is public.

doDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

Create New Ticket Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/createNewTicket"

Saving a Ticket

The saveTicket actor-chain allows an agent to save a ticket.

Parameter Description

ticketId The ID of the ticket to save.

Save Ticket Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"2203\"}" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/saveTicket"

Associating a Ticket

The associateTicket actor-chain allows an agent to associate a ticket.

Parameter Description

ticketId The ID of the ticket to associate.

associatedTicketId The ID of the associated ticket.

6 Internal REST MVC Service Call Examples 189

Parameter Description

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Provides a ticket disposition option.

reasonCode Provides a disposition reason code.

ticketNote Provides a note associated with the ticket.

subStatus Provides a sub-status for the ticket.

Associate Ticket Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"2203\", \"associatedTicketId\" : \"2200\"}""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/associateTicket"

Escalating a Ticket

The escalateTicket actor-chain allows an agent to escalate a ticket.

Parameter Description

ticketId The ID of the ticket to escalate.

escalationLevel The level to which the ticket should be escalated.

group The group to which the ticket should be escalated.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Escalate Ticket Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" –d

190 6 Internal REST MVC Service Call Examples

"{\"ticketId\" : \"2203\" \"escalationLevel\" : \"Tier2\" }""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/escalateTicket"

Closing a Ticket

The closeTicket actor-chain allows an agent to close a ticket.

Parameter Description

ticketId The ID of the ticket to close.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Close Ticket Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"ticketId\" : \"2203\" }" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/closeTicket"

Releasing a Ticket

The releaseTicket actor-chain allows an agent to release a ticket.

Parameter Description

ticketId The ID of the ticket to release.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

6 Internal REST MVC Service Call Examples 191

Parameter Description

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Release Ticket Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"2203\" }" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/releaseTicket"

Deferring a Ticket

The deferTicket actor-chain allows an agent to defer a ticket.

Parameter Description

ticketId The ID of the ticket to defer.

date The date to which to defer the ticket.

retain Boolean option to retain the ticket or not.

share Identifies if the ticket should be shared or not.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Defer Ticket Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"10603\", \"retain\" : \"true\", \"reasonCode\" : \"NeedHelp\"}""http://localhost:8181/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/deferTicket"

192 6 Internal REST MVC Service Call Examples

Reassigning a Ticket

The reassignTicket actor-chain allows an agent to reassign a ticket.

Parameter Description

ticketId The ID of the ticket to reassign.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the

agent.

reassignAgent The agent to which the ticket should be assigned.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Reassign Ticket Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"2203\", \"reassignAgent\" : \"agent007\" }""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/reassignTicket"

Sending a Ticket to a Group

The sendToGroup actor-chain allows an agent to send a ticket to a specific group.

Parameter Description

ticketId The ID of the ticket to send.

group The group to which the ticket should be sent.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

6 Internal REST MVC Service Call Examples 193

Parameter Description

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Send Ticket to Group Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"2203\" \"group\" : \"MyTicketQueue\" }""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/sendToGroup"

Closing a Ticket as Duplicate

The closeAsDuplicate actor-chain allows an agent to close a ticket that has been identified as a duplicate.

Parameter Description

ticketId The ID of the ticket to close.

duplicateTicketId The ID of the duplicated ticket.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

publicNote Identifies if the ticket note is public.

subStatus Provides a sub-status for the ticket.

Close Ticket as Duplicate Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"458514\" \"duplicateTicketId\" : \"2200\" }""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/closeAsDuplicate"

Editing a Ticket

The beginEdit actor-chain allows an agent to begin editing a ticket.

194 6 Internal REST MVC Service Call Examples

Parameter Description

ticketId The ID of the ticket to edit.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

subStatus Provides a sub-status for the ticket.

Edit Ticket Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"458514\" }" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/beginEdit"

End Editing a Ticket

The endEdit actor-chain allows an agent to end editing a ticket, saving the information added during the

edit. The endEdit actor-chain also implicitly calls the beginEdit actor-chain, which sets the current ticket to

“isEditable”.

Parameter Description

ticketId The ID of the ticket to edit.

doTicketDispositionPrompt If set to true, will present ticket disposition

prompts to the agent.

dispositionOption Identifies a ticket disposition used for this ticket.

reasonCode Adds a reason code to the ticket.

ticketNote Adds a ticket note to the new ticket.

subStatus Provides a sub-status for the ticket.

parameterMap.priority The ticket priority.

parameterMap.ticketQueue The ticket queue of the ticket.

parameterMap.customerDetails_firstName The first name of the customer associated with

the ticket.

6 Internal REST MVC Service Call Examples 195

Parameter Description

parameterMap.customerDetails_lastName The last name of the customer associated with

the ticket.

parameterMap.customerDetails_phone The phone number of the customer associated

with the ticket.

parameterMap.customerDetails_email The email of the customer associated with the

ticket.

parameterMap.customerDetails_address The address of the customer associated with the

ticket.

parameterMap.customerDetails_city The city of the customer associated with the

ticket.

parameterMap.customerDetails_state The state where the customer who is associated

with the ticket resides.

parameterMap.customerDetails_country The country of the customer associated with the

ticket.

parameterMap.customerDetails_postalCode The postal code of the customer associated with

the ticket.

End Editing Ticket Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"parameterMap\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\":{\"priority\":\"3\",\"ticketQueue\":\"myTicketQueue\",\"customerDetails_firstName\":\"John\",\"customerDetails_lastName\":\"Smith\",\"customerDetails_phone\":\"07876788144\",\"customerDetails_email\":\"jsmith@example.com\",\"customerDetails_address\":\"1 Main Street\",\"customerDetails_city\":\"Berlin\",\"customerDetails_state\":\"MA\",\"customerDetails_country\":\"US\",\"customerDetails_postalCode\":\"01580\"}}, \"ticketId\" : \"458514\"}" "http://localhost:8080/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/endEdit?atg-rest-output=json"

Viewing Active Tickets

The viewActiveTickets actor-chain displays a list of all active ticket. It contains the following parameter:

Parameter Description

sortDirection The way in which you want to sort the list.

sortField The field used to sort the list.

196 6 Internal REST MVC Service Call Examples

Parameter Description

currentPage The paging results of the search to display.

resultsPerPage The number of results to display per page.

View Active Tickets Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"sortField\" : \"id\" \"sortDirection\" : \"desc\", \"currentPage\" : \"0\",\"resultsPerPage\" : \"3\" }" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/TicketActor/viewActiveTickets"

Looking Up a Ticket

The TicketLookupActor allows an agent to look up a ticket. This service calls the TicketLookupDroplet to

provide search parameters. The TicketLookupActor is located at /atg/ticketing/droplet/.

This actor uses the lookup actor-chain.

Parameter Description

searchProperty The name of the ticketing property to search on when performing the lookup.

value The value of the property.

includes Looks up tickets whose searchProperty includes the value provided if set to

true. If set to false, searches using a straight comparison.

ticketId The ID of the ticket.

startIndex The first ticket to return. This property is used to break large query results into

smaller pieces.

numTickets The number of tickets to return.

Lookup Ticket Examples

The following example looks for tickets that were created on the telephone. The server will respond with a list of

all tickets and the corresponding ticket information that meet the criteria.

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"searchProperty\" : \"creationChannel\" , \"value\" : \"telephony\" }""http://localhost:8180/rest/model/atg/ticketing/droplet/TicketLookupActor/lookup"

This example looks for a specific ticket, which is identified by its ticket ID.

6 Internal REST MVC Service Call Examples 197

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"ticketId\" : \"22003\" }" "http://localhost:8180/rest/model/atg/ticketing/droplet/TicketLookupActor/lookup"

The server response to this example might be similar to the following:

{ "tickets": { "creationChannel": "telephony", "hasPendingOwnership": false, "relatedTickets": [], "escalationCount": 1, "externalTicketSystem": null, "escalationLevel": "Tier3", "pendingTime": null, "activitiesByDate": [{ "abstract": null, "previousSubStatus": { "subStatusName": "Closed", "parentStatus": "Closed" }, "application": "Agent", "textContent": null, "newSubStatus": { "subStatusName": "ReOpened", "parentStatus": "Open" }, "reason": null, "inProgress": null, "type": "statusChange", "id": "1700003", "activityData": null, "userName": null, "creationTime": { "time": 1375785034000 }, "public": false, "heading": null }, { "abstract": null, "application": "Agent", "textContent": null, "reason": null, "inProgress": null, "type": "agentAssignment", "id": "1700004", "activityData": null, "userName": null, "creationTime": { "time": 1375785034000 }, "public": false, "heading": null }, { "abstract": null, "application": "Agent",

198 6 Internal REST MVC Service Call Examples

"textContent": null, "reason": null, "inProgress": null, "type": "agentAssignment", "id": "1600009", "activityData": null, "userName": null, "creationTime": { "time": 1375716548000 }, "public": false, "heading": null }, { "abstract": null, "previousSubStatus": { "subStatusName": "Closed", "parentStatus": "Closed" }, "application": "Agent", "textContent": null, "newSubStatus": { "subStatusName": "ReOpened", "parentStatus": "Open" }, "reason": null, "inProgress": null, "type": "statusChange", "id": "1600008", "activityData": null, "userName": null, "creationTime": { "time": 1375716548000 }, "public": false, "heading": null }, { "abstract": null, "previousSubStatus": { "subStatusName": "ReOpened", "parentStatus": "Open" }, "application": "Agent", "textContent": null, "newSubStatus": { "subStatusName": "Closed", "parentStatus": "Closed" }, "reason": null, "inProgress": null, "type": "statusChange", "id": "1600010", "activityData": null, "userName": null, "creationTime": { "time": 1375716548000 }, "public": false, "heading": null

6 Internal REST MVC Service Call Examples 199

}, { "abstract": null, "previousSubStatus": { "subStatusName": "Open", "parentStatus": "Open" }, "application": "Agent", "textContent": null, "newSubStatus": { "subStatusName": "Closed", "parentStatus": "Closed" }, "reason": null, "inProgress": null, "type": "statusChange", "id": "1600005", "activityData": null, "userName": null, "creationTime": { "time": 1375716201000 }, "public": false, "heading": null }, { "abstract": null, "application": "Agent", "textContent": null, "reason": null, "inProgress": null, "type": "agentAssignment", "id": "999999", "activityData": null, "userName": null, "creationTime": { "time": 1375276229000 }, "public": false, "heading": null }], "id": "2200", "duplicateOfTicketId": null, "loadedTimestamp": null, "slaBaseTimestamp": { "time": 1374054964000 }, "description": null, "priority": 0, "lastModifiedInDays": 0, "customerDetails": null, "creationTime": { "time": 1374054650000 }, "application": "Agent", "lastModified": { "time": 1376639939000 }, "originatingTicketId": null, "ageInDays": 30,

200 6 Internal REST MVC Service Call Examples

"mergeable": true, "externalReferences": [], "inProgressActivity": null, "loaded": false, "externalTicketId": null, "inboundChannelAddress": null, "subStatus": { "subStatusName": "Open", "parentStatus": "Open" }, "pushable": false, "due": null, "releaseTime": null, "defaultOutboundChannel": "unknown", "user": null, "displayId": "2200", "ticketQueue": null }}

Searching for a Ticket

The TicketSearchActor allows an agent to search for ticket. This service uses the

searchTicketFormHandler when working with search parameters. The TicketSearchActor is located at /

atg/svc/ui/formhandlers/.

This actor uses the findTicket actor-chain.

Parameter Description

currentPage The paging results of the search to display.

resultsPerPage The number of results to display per page.

sortDirection The way in which you want to sort the list.

sortField The field used to sort the list.

parameterMap.id The ID of the ticket to find.

parameterMap.subStatus_subStatusName The name of the sub-status of the ticket.

parameterMap.ticketQueue_id The ticket queue ID of the ticket.

parameterMap.escalationLevel The escalation level of the ticket.

parameterMap.customerDetails_firstName The first name of the customer associated with the

ticket.

parameterMap.customerDetails_lastName The last name of the customer associated with the

ticket.

6 Internal REST MVC Service Call Examples 201

Parameter Description

parameterMap.customerDetails_phone The phone number of the customer associated with

the ticket.

parameterMap.customerDetails_email The email address of the customer associated with the

ticket.

parameterMap.description The ticket description.

parameterMap.owningAgentId The agent ID who owns the ticket.

parameterMap.dates_byCreatedDate The created by date.

parameterMap.dates_pastOrFromTo A date range from which to retrieve tickets.

parameterMap.dates_past A date after which tickets will be retrieved. For

example, tickets created after December 1, 2013.

parameterMap.dates_past2 A secondary date after which tickets will be retrieved.

parameterMap.dates_fromDate A date from which tickets will be retrieved. Use in

tandem with dates_toDate to set a date range.

parameterMap.dates_toDate A date to which tickets will be retrieved. Use in

tandem with dates_fromDate to set a date range.

parameterMap.dates_pastOrFromTo2 An optional additional past or from date criteria.

parameterMap.dates_byLastModified Search for tickets by the date of the last modification.

parameterMap.dates_modifiedFrom Search for tickets modified from a specific date.

parameterMap.dates_modifiedTo Search for a ticket modified up to a specific date.

Search Tickets Examples

The following example searches for a specific ticket using the ticket ID.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"parameterMap\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\":{\"id\":\"460916\"}}}" "http://localhost:8080/rest/model/atg/svc/ui/formhandlers/TicketSearchActor/findTickets"

The following example will return a list of all open tickets:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"sortField\" : \"id\" ,\"sortDirection\" : \"desc\",\"parameterMap\":{\"atg-rest-class-type\":\"java.util.HashMap\", \"atg-rest-values\":{\"id\":\"\" ,\"subStatus_subStatusName\":\"Open\", \"ticketQueue_id\":\"\",\"escalationLevel\":\"\",\"customerDetails_firstName\":\"\",\"customerDetails_lastName\":\"\",\"customerDetails_phone\":\"\",\"customerDetails_email\":\"\", \"description\":\"\",

202 6 Internal REST MVC Service Call Examples

\"owningAgentId\":\"\", \"dates_byCreatedDate\":\"\", \"dates_pastOrFromTo\":\"\",\"dates_past\":\"\", \"dates_past2\":\"\", \"dates_fromDate\":\"\",\"dates_toDate\":\"\",\"dates_pastOrFromTo2\":\"\", \"dates_byLastModified\":\"\",\"dates_modifiedFrom\":\"\", \"dates_modifiedTo\":\"\"}}}" "http://localhost:8080/rest/model/atg/svc/ui/formhandlers/TicketSearchActor/findTickets"

Reviewing a Ticket Status

The TicketStatusDescriptionActor allows an agent to look up a ticket’s status. This actor is located at /

atg/ticketing/TicketStatusDescriptorActor.

This actor uses the statusDescription actor-chain.

Parameter Description

descriptionId The ID of the ticket description.

baseName The name of the ticket status.

elementName The element name of the ticket status.

Ticket Status Description Example

The following example looks for tickets that have a status of CLOSED.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"baseName\" : \"STATUS\", \"elementName\" : \"element\", \"descriptionId\" :\"Closed\"}" "http://localhost:8080/rest/model/atg/ticketing/TicketStatusDescriptionActor/statusDescription"

Viewing a Customer

The /atg/svc/agent/ui/formhandlers/ServiceUIProfileActor contains the viewCustomer actor-

chain:

Parameter Description

customerId The ID of the customer to view.

View Customer Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{

6 Internal REST MVC Service Call Examples 203

\"customerId\" : \"se-570050\"}" "http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/ServiceUIProfileActor/viewCustomer"

Working with Customer Profiles

The /atg/svc/agent/ui/formhandlers/CustomerProfileActor contains the following actor-chains:

Actor-Chain Description

create Creates a new customer profile.

update Updates an existing customer profile.

addNote Adds a note to a customer profile.

Creating a New Customer Profile

The create actor-chain is used to create a new customer profile. This actor-chain is also used to create a new

Commerce Service Center account when the orderId and saveCreditCards parameters are used.

Parameter Description

firstName The first name of the new customer.

middleName The middle name or initial of the new customer.

lastName The last name of the new customer.

email The e-mail address of the new customer.

login The customer’s login.

password The customer’s password.

dateOfBirth The customer’s date of birth.

orderId Used when creating an account. Indicates the order ID. If this property is set,

and saveCreditCards is set to true, copies the credit card information from

the order to the user’s profile. Used with Commerce Service Center only.

saveCreditCards Used when creating an account. Indicates if the credit card information for the

customer should be saved. Used with Commerce Service Center only.

address.address1 The first address field associated with the customer’s address.

204 6 Internal REST MVC Service Call Examples

Parameter Description

address.address2 The second address field associated with the customer’s address.

address.city The city associated with the customer’s address.

address.companyName A company name associated with the customer’s address.

address.country A country associated with the customer’s address.

address.county A county associated with the customer’s address.

address.jobTitle A job title associated with the customer’s address.

address.postalCode The postal code associated with the customer’s address.

address.faxNumber A fax number associated with the customer’s address.

address.firstName The first name of the customer associated with the address.

address.middleName The middle name or initial of the customer associated with the address.

address.lastName The last name of the customer associated with the address.

address.phoneNumber The phone number associated with the customer’s address.

address.prefix A prefix associated with the customer, such as Mr. or Dr.

address.state The state associated with the customer’s address.

address.suffix A suffix associated with the customer, such as Jr.

Create New Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"firstName\":\"Bill\", \"middleName\":\"T\", \"lastName\":\"Hitchock\",\"email\":\"bill18@example.com\", \"login\":\"bill18\", \"password\":\"tempPassword\", \"dateOfBirth\":\"AUG 30, 1970\", \"address\":{\"atg-rest-class-type\": \"java.util.HashMap\", \"atg-rest-values\":{\"phoneNumber\":\"555-111-2222\"}} }" "http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/CustomerProfileActor/create"

Create New Customer Account Example

The following example shows how you can create a new C account based upon a customer profile by including

the orderId and the saveCreditCards parameters. This service is used specifically on the Commerce Service

Center Order Completion page, once you have created and completed an order. You could use this service to

create a new user, and then copy the payment information from the order into the user’s profile:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"orderId\":\"o99720003\", \"saveCreditCards\":true, \"firstName\":\"Bill\",\"middleName\":\"T\", \"lastName\":\"Hitchock\", \"email\":\"bill14@example.com\",\"login\":\"bill14\", \"password\":\"tempPassword\", \"dateOfBirth\":

6 Internal REST MVC Service Call Examples 205

\"AUG 30, 1970\", \"address\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\": {\"phoneNumber\":\"555-111-2222\"}} }""http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/CustomerProfileActor/create"

Updating an Existing Customer Profile

The update actor-chain is used to update a customer profile.

Parameter Description

firstName The first name of the customer.

middleName The middle name or initial of the customer.

lastName The last name of the customer.

email The e-mail address of the customer.

dateOfBirth The customer’s date of birth.

address.address1 The first address field associated with the customer’s address.

address.address2 The second address field associated with the customer’s address.

address.city The city associated with the customer’s address.

address.companyName A company name associated with the customer’s address.

address.country A country associated with the customer’s address.

address.county A county associated with the customer’s address.

address.jobTitle A job title associated with the customer’s address.

address.postalCode The postal code associated with the customer’s address.

address.faxNumber A fax number associated with the customer’s address.

address.firstName The first name of the customer associated with the address.

address.middleName The middle name or initial of the customer associated with the address.

address.lastName The last name of the customer associated with the address.

address.phoneNumber The phone number associated with the customer’s address.

address.prefix A prefix associated with the customer, such as Mr. or Dr.

address.state The state associated with the customer’s address.

address.suffix A suffix associated with the customer, such as Jr.

206 6 Internal REST MVC Service Call Examples

Update Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"firstName\":\"Bill\", \"middleName\":\"Theodore\", \"lastName\":\"Hitchock\",\"email\":\"william13@example.com\", \"dateOfBirth\":\"AUG 30, 1972\",\"address\":{\"atg-rest-class-type\":\"java.util.HashMap\", \"atg-rest-values\":{\"address1\":\"333 Main Street\", \"address2\":\"Suite 900\",\"city\":\"Tacoma\",\"state\":\"WA\", \"country\":\"USA\", \"postalCode\":\"00123\", \"phoneNumber\":\"555-111-2225\"}} }" "http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/CustomerProfileActor/update"

Adding a Note to a Customer Profile

The addNote actor-chain is used to create a note that is included in the customer profile.

Parameter Description

comment The text of the note that is attached to the customer profile.

Add Customer Profile Note Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"comment\":\"Customer has many loyalty points that they should use.\" }""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/CustomerProfileActor/addNote"

Searching for a Customer Profile

The atg/svc/agent/ui/formhandlers/CustomerSearchTreeQueryActor contains actor-chains that

perform the following:

Actor-Chain Description

search Searches for a customer profile.

clearForm Clears the saved session search request.

The search actor-chain is used to search for customer profiles. It identifies the way that the results will display,

including the paging and sort order.

6 Internal REST MVC Service Call Examples 207

Parameter Description

fieldCount The array size of the fields returned.

pageSize The number of results per page. The default is set to 10.

pageNum The page number within the pages of results This parameter is zero-based, with

the default set to 0.

maxResults The maximum number of results to display. The default is set to 100.

docProps Which properties should be returned for each result. The default is set to all.

docSort Type of sorting used to display the results. The default is strprop. For number

fields, use numprop sorting.

docSortOrder Sets the sort order as ascending or descending. The default is set to ascending.

docSortProp The field used to sort the results on. The default is lastName.

saveRequest Identifies if the request should be saved within the session. The default is true.

fields[].name The order property name.

fields[].op The operation, which should be set to starts.

field[].value The value that is used for searching this field.

Search Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"pageNum\":0, \"pageSize\":2, \"fieldCount\":\"1\", \"fields\":{\"atg-rest-class-type\":\"java.util.ArrayList\", "atg-rest-class-descriptor\" :{ \"atg-rest-values\" : {\"container-class\" : \"java.util.ArrayList\",\"element-class\":\"atg.textsearch.client.Field\"}}, \"atg-rest-values\":[{\"atg-rest-class-type\":\"atg.textsearch.client.Field\", \"name\":\"lastName\",\"op\": \"starts\",\"value\": \"t\"} ]}}" "http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/CustomerSearchTreeQueryActor/search"

The server response may be similar to the following:

{ "searchResponse": {"items": [ { "lastName": "Taylor", "postalCode": "89501", "phoneNumber": "2125558105", "email": "chuck@example.com", "profileId": "se-570105", "login": "chuck@example.com", "firstName": "Chuck" },

208 6 Internal REST MVC Service Call Examples

{ "lastName": "Thomas", "postalCode": "59101", "phoneNumber": "2125558855", "email": "juan@example.com", "profileId": "se-570056", "login": "juan@example.com", "firstName": "Juan" } ]}, "pagesAvailable": 2}

Clearing a Customer Search Session

The clearForm actor-chain is used to clear the saved session search request.

Properties: None

Clear Customer Search Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/CustomerSearchTreeQueryActor/clearForm"

Selecting a Customer to Work On

The ChangeCurrentCustomerActor allows an agent to select a customer and make them the current

customer in the Commerce Service Center global context area. This enables an agent to work on the customer

and any associated tickets. This actor uses the selectCustomer actor-chain to obtain customer information.

Additionally, this actor can be configured to present ticket disposition information. This actor is located at: /

atg/svc/agent/ui/formhandlers/ChangeCurrentCustomerActor.

Parameter Description

customerId The ID of the customer to select.

doWarnings If set to true, will present a warning to the agent when

proceeding to the new site.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the

agent.

dispositionOption If doTicketDispositionPrompt is selected, this provides a

ticket disposition option.

reasonCode If doTicketDispositionPrompt is selected, this provides a

ticket disposition reason code.

6 Internal REST MVC Service Call Examples 209

Parameter Description

ticketNote Used to provide a note associated with the ticket.

publicNote Identifies if the ticket note is public.

Select Customer to Work On Example

This example confirms the ticket disposition.

curl -x 127.0.0.1:8888 -L -v -b agent_cookies.txt -H "Content-Type:application/json" -d "{ \"customerId\" : \"480010\", \"doWarnings\":true,\"doTicketDispositionPrompt\":true, \"dispositionOption\":\"save\" }""http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/ChangeCurrentCustomerActor/selectCustomer"

This example makes changes to the ticket disposition.

curl -x 127.0.0.1:8888 -L -v -b agent_cookies.txt -H "Content-Type:application/json" -d "{ \"customerId\" : \"480010\", \"doWarnings\":false,\"doTicketDispositionPrompt\":false, \"ticketNote\":\"Junk mail\",\"reasonCode\":\"spam\", \"dispositionOption\":\"close\" }""http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/ChangeCurrentCustomerActor/selectCustomer"

The server response may be similar to this:

{ "isDiscardable": false, "allWarnings": [], "activeTicketDisposition": true}

Working with Customer Profile Addresses

The /atg/svc/agent/ui/profile/AddressBookActor contains the following actor-chains:

Actor-Chain Description

addAddress Adds an address to a customer profile.

updateAddress Updates an address in a customer profile.

210 6 Internal REST MVC Service Call Examples

Actor-Chain Description

deleteAddress Deletes an address from a customer profile.

Adding an Address to a Customer Profile

The addAddress actor-chain is used to create a new address in a customer profile.

Parameter Description

firstName The first name of the customer associated with this address.

middleName The middle name or initial of the customer associated with this address.

lastName The last name of the customer associated with this address.

address1 The first address field of the address.

address2 The second address field of the address.

city The city of the address.

state The state or province of the address.

postalCode The postal code of the address.

country The country of the address.

phoneNumber The phone number associated with this address.

setBillingAddress Boolean value that sets the address as the default billing address.

setShippingAddress Boolean value that sets the address as the default shipping address

Add Address to Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"\firstName\" : "\Jack\", "\lastName\" : "\Dill\", "\address1\" : \"123 Main St\","\city\" : "\Seaside\", "\state\" : "\CA\", "\postalCode\" : "\99021\","\phoneNumber\" : "\123-123-1234\", "\country\" : "\US\" }""http://localhost:8280/rest/model/atg/svc/agent/profile/AddressBookActor/addAddress"

The server response would be:

{"addressId" : "270015"}

6 Internal REST MVC Service Call Examples 211

Editing an Address in a Customer Profile

The updateAddress actor-chain is used to edit or update an existing address in a customer profile.

Parameter Description

addressId Identifies the address to edit.

firstName The first name of the customer associated with this address.

middleName The middle name or initial of the customer associated with this address.

lastName The last name of the customer associated with this address.

address1 The first address field of the address.

address2 The second address field of the address.

city The city of the address.

state The state or province of the address.

postalCode The postal code of the address.

country The country of the address.

phoneNumber The phone number associated with this address.

setBillingAddress Boolean value that sets the address as the default billing address.

setShippingAddress Boolean value that sets the address as the default shipping address.

Edit Customer Profile Address Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"addressId\": \"270015\", \"firstName\":\"Jack\", \"lastName\":\"Dill\",\"address1\":\"124 Main St\", \"city\":\"Seaside\", \"state\":\"CA\",\"postalCode\":\"99022\",\"phoneNumber\":\"555-123-1234\", \"country\":\"US\" }""http://localhost:8280/rest/model/atg/svc/agent/profile/AddressBookActor/updateAddress"

Deleting an Address from a Customer Profile

The deleteAddress actor-chain is used to delete an existing address from a customer profile. Note that you

cannot delete an address that has been identifies as a default billing or shipping address.

212 6 Internal REST MVC Service Call Examples

Parameter Description

addressId Identifies the address to delete.

Delete Customer Profile Address Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"addressId\": \"270015\" }" "http://localhost:8280/rest/model/atg/svc/agent/profile/AddressBookActor/deleteAddress"

Working with Credit Cards Within a Customer Profile

The /atg/commerce/custsvc/repository/CreditCardActor contains actor-chains that perform the

following:

Actor-Chain Description

addCreditCard Adds a new credit card to a customer profile.

updateCreditCard Updates credit card information in a customer’s profile.

deleteCreditCard Deletes a credit card from a customer’s profile.

Adding a Credit Card to a Customer Profile

The addCreditCard actor-chain is used to add a new credit card within a customer profile.

Parameter Description

creditCardType The type of credit card to add.

creditCardNumber The credit card number.

expirationMonth The month the credit card expires.

expirationYear The year the credit card expires.

billingAddressRepositoryId The ID of the billing address repository.

firstName The first name of the customer associated with this billing

address.

6 Internal REST MVC Service Call Examples 213

Parameter Description

middleName The middle name or initial of the customer associated with this

billing address.

lastName The last name of the customer associated with this billing

address.

address1 The first address field of the billing address.

address2 The second address field of the billing address.

city The city of the billing address.

state The state or province of the billing address.

postalCode The postal code of the billing address.

country The country of the billing address.

phoneNumber The phone number associated with this billing address.

setBillingAddress Boolean value that sets the address as the default billing

address.

setShippingAddress Boolean value that sets the address as the default shipping

address.

defaultCreditCardSetDefault If this property is set to true, this becomes the default credit

card.

Add Credit Card to Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"billingAddressRepositoryId\" : \"690024\", \"creditCardType\" : \"Visa\",\"creditCardNumber\" : \"4111111111111111\", \"expirationMonth\" : \"01\",\"expirationYear\" : \"2016\", \"firstName\" : \"Jack\", \"lastName\" : \"Dill\",\"address1\" : \"321 Willow Dr\", \"city\" : \"Beachside\", \"state\" : \"CA\",\"postalCode\" : \"99023\", \"phoneNumber\" : \"617-634-8687\", \"country\" :\"US\", \"createNewAddress\" : \"true\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/repository/CreditCardActor/addCreditCard"

The server response may be similar to the following:

{"creditCardId" : "0012"}

Editing a Credit Card in a Customer Profile

The updateCreditCard actor-chain is used to add a new credit card within a customer profile. This chain can

be used to add a credit card to an existing customer address, or associated it with a new address.

214 6 Internal REST MVC Service Call Examples

Parameter Description

createNewAddress Identifies if a new address will be created in the customer

profile.

creditCardId The ID of the credit card to edit.

creditCardType The type of credit card to edit.

creditCardNumber The credit card number.

expirationMonth The month the credit card expires.

expirationYear The year the credit card expires.

billingAddressRepositoryId The ID of the billing address repository.

firstName The first name of the customer associated with this billing

address.

middleName The middle name or initial of the customer associated with

this billing address.

lastName The last name of the customer associated with this billing

address.

address1 The first address field of the billing address.

address2 The second address field of the billing address.

city The city of the billing address.

state The state or province of the billing address.

postalCode The postal code of the billing address.

country The country of the billing address.

phoneNumber The phone number associated with this billing address.

setBillingAddress Boolean value that sets the address as the default billing

address.

setShippingAddress Boolean value that sets the address as the default shipping

address.

defaultCreditCardSetDefault If set to true, this becomes the default credit card.

Update Credit Card in Customer Profile Example

The following example shows how to update a credit card with an existing address. The createNewAddress

parameter is set to false, indicating that the call should not create a new address.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{

6 Internal REST MVC Service Call Examples 215

\"createNewAddress\":\"false\", \"creditCardId\":\"usercc99050003\",\"billingAddressRepositoryId\":\"380016\", \"creditCardType\":\"Visa\",\"creditCardNumber\":\"4111111111111111\", \"expirationMonth\":\"1\",\"expirationYear\":\"2022\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/repository/CreditCardActor/updateCreditCard"

The following example shows how to update a credit card with a new address. The createNewAddress

parameter is set to true, indicating that the call should create a new address.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"createNewAddress\":\"true\", \"creditCardId\":\"usercc99050003\",\"billingAddressRepositoryId\":\"380016\", \"creditCardType\":\"visa\",\"creditCardNumber\": \"4111111111111111\",\"expirationMonth\":\"1\",\"expirationYear\": \"2023\", \"firstName\":\"John\",\"lastName\":\"Smith\",\"address1\": \"1 Main Street\", \"city\":\"Cambridge\",\ "state\":\"MA\", \"country\":\"USA\",\"postalCode\": \"12468\" }""http://localhost:8280/rest/model/atg/commerce/custsvc/repository/CreditCardActor/updateCreditCard"

Deleting a Credit Card from a Customer Profile

The deleteCreditCard actor-chain is used to delete an existing credit card from a customer profile.

Parameter Description

creditCardId Identifies the credit card to delete.

Delete Credit Card From Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"creditCardId\":\"usercc99020006\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/repository/CreditCardActor/deleteCreditCard"

Viewing a Customer’s Shopping Cart

The /atg/commerce/custsvc/order/ShoppingCartActor contains a single detailed actor-chain, which

is used to view or review a customer’s cart or order, and the summary actor-chain, which provides a summary of

the shopping cart.

Parameters: None

View Customer Cart Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShoppingCartActor/

216 6 Internal REST MVC Service Call Examples

detailed"

The server response may be similar to the following:

{"order": { "lastModifiedTime": 1363200675886, "shippingGroupCount": 1, "paymentGroupCount": 0, "shippingGroups": [{ "specialInstructions": {}, "handlingInstructions": [], "state": 0, "locationId": null, "shippingMethod": "hardgoodShippingGroup "id": "sg110004", "trackingNumber": null, "priceInfo": { "amount": 0, "currencyCode": "USD", "amountIsFinal": false, "discounted": true, "rawShipping": 0 }, "description": "sg110004", "actualShipDate": null, "submittedDate": null, "shipOnDate": null, "shippingAddress": { "middleName": null, "lastName": "Smith", "ownerId": 02443221, "state": "MA", "address1": "One Main Street", "address2": null, "address3": null, "companyName": null, "suffix": null, "city": "Cambridge", "country": "USA", "id": null, "postalCode": "02046", "faxNumber": null, "phoneNumber": "6176378687", "county": null, "email": "jsmith@example.com", "prefix": null, "firstName": "John", "jobTitle": null }, "stateDetail": null }], "commerceItems": [{ "id": "ci10000001", "productDisplayName": "Tumbler Glass", "returnedQuantity": 0, "priceInfo": { "amount": 19, "quantityDiscounted": 0, "discountable": true, "priceListId": "listPrices",

6 Internal REST MVC Service Call Examples 217

"onSale": false, "rawTotalPrice": 19, "currencyCode": "USD", "amountIsFinal": false, "listPrice": 19, "discounted": false, "currentPriceDetailsSorted": [{ "amount": 19, "itemPriceInfo": null, "currencyCode": "USD", "tax": 0, "range": { "lowBound": 0, "class": "atg.core.util.Range", "highBound": 0, "size": 1 }, "amountIsFinal": false, "discounted": false, "quantity": 1, "detailedUnitPrice": 19 }], "salePrice": 0 }, "catalogId": null, "quantity": 1, "catalogRefId": "xsku2085", "catalogKey": "en_US", "productId": "xprod2085" }], "id": "o110001", "siteId": "homeSite", "taxPriceInfo": { "amount": 0, "currencyCode": "USD", "countyTax": 0, "amountIsFinal": false, "countryTax": 0, "discounted": false, "stateTax": 0, "cityTax": 0, "districtTax": 0 }, "priceInfo": { "amount": 19, "total": 19, "shipping": 0, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": false, "manualAdjustmentTotal": 0, "rawSubtotal": 19, "discountAmount": 0 }, "paymentGroups": [], "profileId": "220008", "creationTime": 1363200429849, "relationships": [{ "id": "r100001",

218 6 Internal REST MVC Service Call Examples

"amount": 0, "relationshipType": "SHIPPINGQUANTITY", "returnedQuantity": 0, "shippingGroupId": "sg110004", "commerceItemId": "ci10000001", "quantity": 1 }], "totalCommerceItemCount": 1}}

Working with a Customer’s Shopping Cart

The CartModifierActor contains several actor-chains that modify the customer’s shopping cart. The path for

this actor is /atg/commerce/custsvc/order/CartModifierActor.

This actor contains the following actor-chains:

Actor-Chain Description

addMultipleItemsToOrder Adds multiple items to a shopping cart.

addItemToOrder Adds items from a catalog, wish/gift list to a

shopping cart by SKUI ID.

setOrder Updates the shopping cart by SKU ID.

setOrderByCommerceId Updates the shopping cart by commerce ID.

setOrderByRelationshipID Updates the shopping cart by shipping group

relationship ID.

removeAndAddItemToOrder Removes and item and then adds it to the shopping

cart.

removeItemFromOrder Removes an item from the shopping cart using the

SKU.

removeItemFromOrderByRelationshipId Removes an item from the shopping cart using the

Relationship ID.

moveToPurchaseInfo Checks out the order from the shopping cart page

using the SKU.

moveToPurchaseInfoByCommerceId Saves the shopping cart and continues to the next

step in the checkout process using the commerce

ID.

moveToPurchaseInfoByRelId Saves the shopping cart and continues to the next

step in the checkout process using the shipping

group relationship ID.

6 Internal REST MVC Service Call Examples 219

Actor-Chain Description

changeSKUs Changes the SKU of one or more commerce items in

the current order.

Adding Multiple Items to a Customer’s Shopping Cart

The addMultipleItemsToOrder actor-chain is used when adding more than one item to the customer’s

shopping cart.

Parameter Description

addItemCount The number of items being added to the shopping cart. This is different than

the quantity of each product being added, this is the items array size.

items.catalogRefId The catalog reference ID.

items.productId The ID of the product to add to the shopping cart.

items.quantity The number of each product being added to the shopping cart. For example,

two sweaters or four pairs of shoes.

items.locationId Used only for in-store pickup. This identifies the location of the store.

items.siteId Identifies the site associated with the product.

items.giftlistId Used only when adding gift or wishlist items to the shopping cart. Identifies

the ID of the list.

items.giftlistItemId Used only when adding gift or wishlist items to the shopping cart. Identifies

the ID of the list item.

Add Multiple Items to Customer Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"addItemCount\": 3, \"items\": {\"atg-rest-class-type\":\"java.util.ArrayList\",\"atg-rest-values\": [{\"atg-rest-class-type\":\"atg.commerce.order.purchase.AddCommerceItemInfo\", \"catalogRefId\":\"xsku1043\",\"productId\": \"xprod1015\",\"quantity\": 1},{\"atg-rest-class-type\":\"atg.commerce.order.purchase.AddCommerceItemInfo\",\"catalogRefId\":\"xsku60325\",\"productId\": \"xprod40028\",\"quantity\":2},{\"atg-rest-class-type\":\"atg.commerce.order.purchase.AddCommerceItemInfo"\,\"catalogRefId\":\"xsku1001\",\"productId\": \"xprod1001\",\"quantity\": 3} ]}}""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addMultipleItemsToOrder"

220 6 Internal REST MVC Service Call Examples

Adding Items to a Customer’s Shopping Cart

The addItemToOrder actor-chain is used to add a single item to a customer’s shopping cart. It also is used to

add an item from a customer’s gift/wish list to a shopping cart, as well as adding an item to an in-store pickup

order:

Parameter Description

catalogRefIds The catalog reference ID.

productId The ID of the product to add to the shopping cart.

quantity The number of each product being added to the shopping cart. For example, two

sweaters or four pairs of shoes.

siteId Identifies the site associated with the product.

locationId Used only for in-store pickup, identifies the location of the store.

addToWishlist This Boolean parameter is used only for adding wish list items to the shopping

cart.

giftlistItemId Used only for adding gift/wish list items. Identifies the list item ID.

giftlistId The ID of the gift list.

Add Item to Customer’s Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\": \"xsku1043\",\"productId\": \"xprod1015\",\"quantity\": 1}""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addItemToOrder"

Add Item to Customer’s In-Store Pickup Example

Note the use of the locationId to identify the store from where the item will be picked up.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\" : \"xsku2085\", \"productId\" : \"prod10004\", \"locationId\" :\"AventuraMall\", \"quantity\": 8}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addItemToOrder"

Add Item From Customer’s Gift List Example

Note the use of the giftlistId and the giftlistItemId.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\" : \"xsku2085\", \"productId\" : \"xprod2085\", \"giftlistId\" :\"gl40007\", \"giftlistItemId\" : \"gi40001\", \"quantity\": 1}""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/

6 Internal REST MVC Service Call Examples 221

addItemToOrder"

Add Item From Customer’s Wish List Example

This example is similar to the Gift List example, however it uses the addToWishlist instead of the giftlistId.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"addToWishlist\" : \"true\", \"catalogRefIds\" : \"xsku2085\", \"productId\" :\"xprod2085\", \"giftlistItemId\" : \"gi40001\", \"quantity\": 1}""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addItemToOrder"

Updating the Customer’s Shopping Cart by SKU ID

The setOrder actor-chain updates the quantity of items within the customer’s shopping cart using SKU IDs.

Parameter Description

removalCatalogRefIds The optional list of catalog reference IDs (SKU ID) to remove from the

order.

Update Customer’s Shopping Cart by SKU ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrder?xsku1043=2"

Updating the Customer’s Shopping Cart by Commerce ID

The setOrderByCommerceId actor-chain updates the quantities of items within the customer’s shopping cart

using the commerce ID. Note that this actor-chain is also used to perform a price override. Refer to the Adjusting

a Customer’s Order (page 265) section for information on price overrides.

Parameter Description

removalCommerceIds The optional list of commerce item IDs to remove from the order.

Update Customer’s Shopping Cart by Commerce ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrderByCommerceId?ci111000001=3"

222 6 Internal REST MVC Service Call Examples

Updating the Customer’s Shopping Cart By Shipping Group Relationship ID

The setOrderByRelationshipId actor-chain is used to update the quantities of items within the customer’s

shopping cart using the CommerceItem or the shipping group relationship ID.

Parameter Description

removalRelationshipIds The list of relationship IDs to remove from the order.

Update Customer’s Shopping Cart by Relationship ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrderByRelationshipId?r99090004=4"

Removing and Adding an Item to the Customer’s Shopping Cart

The removeAndAddItemToOrder actor-chain is used to removes items from the order and then adds it to the

order.

Parameter Description

catalogRefIds The catalog reference ID.

productId The ID of the product.

quantity The quantity of the product.

removalCommerceIds The ID given to the item, or to a list of commerce items, that should be removed

from the order.

Move an Item to the Customer’s Cart Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"catalogRefIds\":\"xsku1043\",\"productId\": \"xprod1015\",\"quantity\": 1,\"removalCommerceIds\":\"ci116000002\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/removeAndAddItemToOrder"

Removing an Item From the Customer’s Shopping Cart

The removeItemFromOrder actor-chain removes items from the customer’s shopping cart using the commerce

ID.

6 Internal REST MVC Service Call Examples 223

Parameter Description

removalCommerceIds The list of commerce item IDs to remove from the order.

Remove Item From Customer’s Cart Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/removeItemFromOrder?removalCommerceIds=ci115000001"

Removing an Item From a Customer’s Shopping Cart By Relationship ID

The removeItemFromOrderByRelationshipId actor-chain is used to remove items from the customer’s

shopping cart using the commerceItem or the shipping group relationship ID.

Parameter Description

removalRelationshipIds The list of relationship IDs to remove from the order.

Remove Item From Customer’s Cart by Relationship ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/removeItemFromOrderByRelationshipId?removalRelationshipIds=r99160002"

Starting the Checkout Process with SKU ID

The moveToPurchaseInfo actor-chain starts the checkout process by verifying for changes in the order. The

current order’s SKU quantities are passed in to initiate the checkout process.

Parameters: None

Continue the Checkout Process with SKU ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/moveToPurchaseInfo?sku40051=1"

Starting the Checkout Process with Commerce ID

The moveToPurchaseInfoByCommerceId actor-chain starts the checkout process. The current order’s

commerce ID quantities are passed in to initiate the checkout process.

224 6 Internal REST MVC Service Call Examples

Parameters: None

Continue the Checkout Process with Commerce ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/moveToPurchaseInfoByCommerceId?ci4000006=1"

Starting the Checkout Process with Relationship ID

The moveToPurchaseInfoByRelId actor-chain starts the checkout process. The current order’s relationship ID

quantities are passed in to initiate the checkout process.

Parameters: None

Continue the Checkout Process with Relationship ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/moveToPurchaseInfoByRelId?r99290001=1"

Changing the SKU of an Item

The changeSkus actor-chain changes the SKU of one or more commerce items in the current order.

Parameters: To modify the SKU of an item, pass the commerce ID prefixed by SKUCNG with the new SKU ID as

the value: SKUCNG:{CommerceItem ID}={SKU ID}

Change SKU Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/changeSkus?SKUCNG:ci115000001=2"

Assisting the Customer with the Shipping Page

The ShippingGroupActor contains several actor-chains that modify the Shipping page. The path for this actor

is /atg/commerce/custsvc/order/ShippingGroupActor.

Actor-Chain Description

getShippingGroups Initializes and retrieves avilable shipping groups.

6 Internal REST MVC Service Call Examples 225

Actor-Chain Description

applySingleShippingGroup Used to select a single shipping group.

applyMultipleShippingGroups Used to set multipe shipping groups.

applyShippingMethods Applies shipping methods to both single and multiple

shipping groups.

splitShippingInfos Splits the shipping between specified shipping groups.

getAllCommerceItemShippingInfos Obtains all of the Commerce Item Shipping Info (CISI).

Displaying Available Shipping Groups

The getShippingGroups actor-chain displays all of the shipping groups that are available.

Parameter Description

init Clears the shipping group infos on the ShippingGroupDroplet and

relitializes the properties.

Display Available Shipping Groups Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"init\" : \"true\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShippingGroupActor/getShippingGroups"

The server response may be similar to the following:

{ "ci10000002": { "shippingGroups": {}, "allShippingGroupTypes": ["hardgoodShippingGroup"] }, "shippingGroups": {}, "shippingInfos": {"ci10000002": [{ "handlingInstructionInfos": [], "commerceItemId": "ci10000002" }]}, "allShippingGroupTypes": ["hardgoodShippingGroup"], "commonShippingGroupTypes": ["hardgoodShippingGroup"]}

Specifying a Single Shipping Group

The applySingleShippingGroup actor-chain identifies a single shipping group for the current order.

226 6 Internal REST MVC Service Call Examples

Parameter Description

shipToAddressNickname Identifies the nickname of the shipping group.

Specify Single Shipping Group Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"shipToAddressNickname\" : \"HomeAddress\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShippingGroupActor/applySingleShippingGroup"

Specifying Multiple Shipping Groups

The ApplyMultipleShippingGroups actor-chain identifies one or more shipping groups for the current order.

Note that shippingGroupNames must be configured in the Commerce Item Shipping Info(CISI) list. Refer to the

Core Commerce Programming Guide for further information.

Parameter Description

cisicount Identifies the array size of the cisiList.

cisiList.shippingGroupName The name of the shipping group in the Commerce Item Shipping

Info (CISI) list.

cisiList.shippingMethod The name of the shipping method in the Commerce Item

Shipping Info (CISI) list.

Specify Multiple Shipping Groups Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"cisicount\" : \"2\", \"cisiList\" :{ \"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\": [{ "atg-rest-class-type":\"atg.commerce.order.purchase.CommerceItemShippingInfo\", \"shippingGroupName\" :\"Address\"}, { \"atg-rest-class-type\":\"atg.commerce.order.purchase.CommerceItemShippingInfo\",\"shippingGroupName\" :\"Address##0\"}]}}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShippingGroupActor/applyMultipleShippingGroups"

Splitting Items into Different Shipping Groups

The splitShippingInfos actor-chain splits the shipping between shipping groups.

6 Internal REST MVC Service Call Examples 227

Parameter Description

cisicount Identifies the array size of the cisiList.

cisiList.quantity The original quantity value that needs to be split.

cisiList.splitQuantity The quantity that should be moved to the other shipping

group.

cisiList.shipppingGroupName This is the name of the shipping group in which the item

will be available.

cisiList.splitShippingGroupName This is the name of the split shipping group.

Split Items into Different Shipping Groups Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"cisicount\" : \"1\", \"cisiList\" :{ \"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\": [ { \"atg-rest-class-type\":\"atg.commerce.order.purchase.CommerceItemShippingInfo\", \"quantity\" : \"5\",\"splitQuantity\" : \"2\", \"shippingGroupName\" : \"Address\",\"splitShippingGroupName\" : \"Address##0\"}]}}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShippingGroupActor/splitShippingInfos"

Applying Shipping Methods

The applyShippingMethods actor-chain applies shipping methods to shipping groups and then continues

onto the billing process.

Parameter Description

shippingGroupscount Identifies the array size of the shipping groups.

shippingGroups.shippingMethod Identifies the shipping methods for each shipping group.

Apply Shipping Method Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"shippingGroupscount\" : \"1\", \"shippingGroups\" : {\"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\": [{\"atg-rest-class-type\":\"atg.commerce.order.purchase.CommerceItemShippingInfo\", \"shippingMethod\" :\"Ground\"}]}}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShippingGroupActor/applyShippingMethods"

228 6 Internal REST MVC Service Call Examples

Displaying All Available Shipping Methods

The AvailablePricedShippingMethodsActor is used to display the available shipping methods. The path to

this actor is: /atg/commerce/custsvc/pricing/AvailablePricedShippingMethodsActor.

This actor contains the getAvailablePricedShippingMethods actor-chain:

Parameters: None

Display All Available Shipping Methods Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/pricing/AvailablePricedShippingMethodsActor/getAvailablePricedShippingMethods"

The server response might be:

{"sg70004": { "Next Day": { "amount": 18.95, "currencyCode": "USD", "rawShipping": 18.95 }, "Two Day": { "amount": 9.5, "currencyCode": "USD", "rawShipping": 9.5 }, "Ground": { "amount": 4.75, "currencyCode": "USD", "rawShipping": 4.75 }}}

Creating New Hardgood Shipping Groups

The CreateHardgoodShippingGroupActor is used to create a new hardgood shipping group. The path to this

actor is: /atg/commerce/custsvc/order/CreateHardgoodShippingGroupActor.

This actor contains the addHardgoodShippingGroup actor-chain:

Parameter Description

firstName The first name of the customer associated with this shipping group.

middleName The middle name or initial of the customer associated with this shipping group.

lastName The last name of the customer associated with this shipping group.

address1 The first address field associated with this shipping group.

6 Internal REST MVC Service Call Examples 229

Parameter Description

address2 The second address field associated with this shipping group.

city The city of the address associated with this shipping group.

state The state of the address associated with this shipping group.

country The country of the address associated with this shipping group.

postalCode The postal code of the address associated with this shipping group.

phoneNumber The phone number of the customer associated with this shipping group.

Create New Hardgood Shipping Group Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"firstName\": \"Joe\",\"lastName\": \"Smith\",\"address1\":\"1 Main St\",\"city\": \"Cambridge\",\"state\": \"MA\",\"country\": \"USA\",\"postalCode\": \"02146\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CreateHardgoodShippingGroupActor/newHardgoodShippingGroup"

Editing a Hardgood Shipping Group

The UpdateHardgoodShippingGroupActor is used to edit shipping groups. The path to this actor is: /atg/

commerce/custsvc/order/UpdateHardgoodShippingGroupActor.

This actor contains the updateHardgoodShippingGroup actor-chain:

Parameter Description

nickname The nickname associated with the shipping group to update.

firstName The first name of the customer associated with this shipping group.

middleName The middle name or initial of the customer associated with this shipping group.

lastName The last name of the customer associated with this shipping group.

address1 The first address field of the address associated with this shipping group.

address2 The second address field of the address associated with this shipping group.

city The city of the address associated with this shipping group.

state The state of the address associated with this shipping group.

country The country of the address associated with this shipping group.

postalCode The postal code of the address associated with this shipping group.

230 6 Internal REST MVC Service Call Examples

Parameter Description

phoneNumber The phone number of the customer associated with this shipping group.

Edit Hardgood Shipping Group Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"nickname\": \"Address\",\"firstName\": \"Jane\",\"lastName\":\"Doe\",\"address1\": \"2 Main St\",\"city\": \"Wilmington\",\"state\":\"MA\",\"country\": \"USA\",\"postalCode\": \"01887\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/UpdateHardgoodShippingGroupActor/updateHardgoodShippingGroup"

Obtaining the Customer’s Current Shipping Info List

The getAllCommerceItemShippingInfos actor-chain obtains all of the Commerce Item Shipping Info (CISI).

Note that you must call this method to initialize the shipping list prior to calling applyShippingGroups.

Parameters: None

Initialize Shipping List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShippingGroupActor/getAllCommerceItemShippingInfos"

Assisting the Customer with the Billing Page

The PaymentGroupActor contains several actor-chains that allow the agent to assist the customer when

working with the billing page. The path for this actor is /atg/commerce/custsvc/order/

PaymentGroupActor.

Actor-Chain Description

getPaymentGroups Displays the customer’s billing information.

getCommerceIdentifierPaymentInfos Gets the Commerce Identifier Payment Info (CIPI).

applyMultiplePaymentGroups Applies multiple payment groups.

claimItem Used to claim store credit or a gift card.

6 Internal REST MVC Service Call Examples 231

Display the Customer’s Payment Groups

The getPaymentGroups actor-chain is used to display the customer’s payment groups.

Parameter Description

init This parameter will initialize initPaymentGroups, initBasedOnOrder and

initOrderPayment groups.

Display Customer Payment Groups Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"init\": \"true\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/PaymentGroupActor/getPaymentGroups"

The server response may be similar to the following:

{"paymentGroups": {"visa - 1111": { "amount": 0, "currencyCode": null, "expirationMonth": "1", "expirationYear": "2022", "paymentId": "pg110012", "creditCardNumber": "1111", "expirationDayOfMonth": null, "billingAddress": { "lastName": "Smith", "postalCode": "02046", "phoneNumber": "6176378687", "email": "jsmith@example.com", "state": "MA", "address1": "One Main Street", "address2": null, "firstName": "John", "city": "Cambridge", "country": "USA" }, "creditCardType": "Visa", "orderId": null}}}

Getting Available Payment Information

The getCommerceIdentifierPaymentInfos actor-chain is used initializes payment lists and obtains the

current payment list.

232 6 Internal REST MVC Service Call Examples

Parameter Description

listId Identifies the payment list to initialize.

Get Available Payment Information Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"listId\" : \"o40001\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/PaymentGroupActor/getCommerceIdentifierPaymentInfos"

The server resopnse may be similar to the following:

{"currentList":[ { "splitPaymentMethod":null," "splitQuantity":0, "splitAmount":0, "commerceIdentifier":{ "commerceItems":[{ "productDisplayName":"Corduroy Pants", "productId":"prod20003", "id":"ci103000003", "priceInfo":{ "currencyCode":"USD", "amount":67, "currentPriceDetailsSorted":[{ "currencyCode":"USD", "detailedUnitPrice":67, "amount":67,"quantity":1 } ]}, "quantity":1, "catalogRefId":"sku40051" }], "id":"o99060003", "priceInfo":{ "total":60.3, "currencyCode":"USD", "discountAmount":6.700000000000003, "amount":60.3, "shipping":0, "tax":0, "rawSubtotal":67 }, "totalCommerceItemCount":1 }, "amount":60.3, "creditCardVerificationNumber":null, "relationshipType":"ORDERAMOUNTREMAINING", "amountRemainingType":"ORDERAMOUNTREMAINING", "quantity":0, "paymentMethod":null, "amountType":"ORDERAMOUNT" }, {

6 Internal REST MVC Service Call Examples 233

"splitPaymentMethod":null, "splitQuantity":0, "splitAmount":0, "commerceIdentifier":{ "commerceItems":[{ "productDisplayName":"Corduroy Pants", "productId":"prod20003", "id":"ci103000003", "priceInfo":{ "currencyCode":"USD", "amount":67, "currentPriceDetailsSorted":[{ "currencyCode":"USD", "detailedUnitPrice":67, "amount":67, "quantity":1 } ]}, "quantity":1, "catalogRefId":"sku40051" }], "id":"o99060003", "priceInfo":{ "total":60.3, "currencyCode":"USD", "discountAmount":6.700000000000003, "amount":60.3, "shipping":0, "tax":0,"rawSubtotal":67 }, "totalCommerceItemCount":1 }, "amount":0, "creditCardVerificationNumber":null, "relationshipType":"ORDERAMOUNT", "amountRemainingType":"ORDERAMOUNTREMAINING", "quantity":0, "paymentMethod":"visa - 1111", "amountType":"ORDERAMOUNT" }]}

Claiming Store Credit or a Gift Certificate

The claimItem actor-chain is used for the customer to claim either store credit, or a gift certificate.

Parameter Description

claimCode The claim code being used by the customer.

Claim Store Credit or Gift Card Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{

234 6 Internal REST MVC Service Call Examples

\"claimCode\": \"sc36b60\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/PaymentGroupActor/claimItem"

Claiming a Customer’s Coupon

The CouponActor is used by a customer to claim a coupon. It is located in: /atg/commerce/

custsvc/promotion/CouponActor.

This actor has the claimCoupon actor-chain:

Parameter Description

couponClaimCode The coupon code that is being provided by the customer.

Claim Customer’s Coupon Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"couponClaimCode\":\"TENSHIP\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/promotion/CouponActor/claimCoupon"

Applying Multiple Payment Groups

The applyMultiplePaymentGroups actor-chain is used to apply multiple payment groups to a customer’s

order. Once the payment groups are applied, the process continues on to Order Review.

Parameter Description

listId The ID of the order.

cipicount The size of the cipiList array.

cipiList.amount Amount that is being applied to the payment group.

cipiList.creditCardVerificationNumber The credit card verification number.

Apply Multiple Payment Groups Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"listId\" : \"o40003\", \"cipicount\" : \"2\", \"cipiList\" :{ \"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\":[{\"atg-rest-class-type\":\"atg.commerce.order.purchase.CommerceIdentifierPaymentInfo\",\"amount\" : \"0.00\",\"creditCardVerificationNumber\" : \"1234\"},{\"atg-rest-class-type\":

6 Internal REST MVC Service Call Examples 235

\"atg.commerce.order.purchase.CommerceIdentifierPaymentInfo\",\"amount\" : \"5.00\", \"creditCardVerificationNumber\" : \"1234\"}]}}""http://localhost:8280/rest/model/atg/commerce/custsvc/order/PaymentGroupActor/applyMultiplePaymentGroups"

Working with Credit Cards Within an Order

The /atg/commerce/custsvc/order/CreateCreditCardActor contains actor-chains that allow an agent to

work with the customer’s credit card information while working on an order:

Actor-Chain Description

getExistingAddresses Initializes the existing addresses in an order.

newCreditCardWithExistingAddress Creates a new credit card payment group with an existing

address in an order.

newCreditCardWithNewAddress Creates a new credit card payment group with a new address

in an order.

Getting a Customer’s Existing Address

The getExistingAddress actor-chain is used to initialize the existing address of the customer. This actor-chain

must be run prior to using the newCreditCardWithExistingAddress actor-chain.

Properties: None

Initialize Customer Existing Address Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CreateCreditCardActor/getExistingAddresses"

Adding a Credit Card to an Existing Address in an Order

The newCreditCardWithExistingAddress actor-chain is used to create a new credit card payment group

with an existing address in an order. Note that the getExistingAddress actor-chain must be run prior to

running this call.

Parameter Description

creditCardType Identifies the address to delete.

236 6 Internal REST MVC Service Call Examples

Parameter Description

creditCardNumber Adds the new credit card number.

expirationMonth Adds the new credit card’s expiration month.

expirationYear Adds the new credit card’s expiration year.

addressIndex Identifies the address associated with this new credit card.

Add Credit Card to Existing Address in Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"addressIndex\": \"0\", \"creditCardType\": \"visa\",\"creditCardNumber\":\"4111111111111111\",\"expirationMonth\": \"1\",\"expirationYear\": \"2020\" }""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CreateCreditCardActor/newCreditCardWithExistingAddress"

Adding a Credit Card to a New Address in an Order

The newCreditCardWithNewAddress actor-chain is used to create a new credit card payment group with an

existing address in an order.

Parameter Description

creditCardType Identifies the address to delete.

creditCardNumber Adds the new credit card number.

expirationMonth Adds the new credit card’s expiration month.

expirationYear Adds the new credit card’s expiration year.

firstName Identifies the first name of the customer associated with this billing address.

middleName The middle name or initial of the customer associated with this billing address.

lastName The last name of the customer associated with this billing address.

address1 The first address field of the billing address.

address2 The second address field of the billing address.

city The city of the billing address.

state The state or province of the billing address.

country The country of the billing address.

postalCode The postal code of the billing address.

6 Internal REST MVC Service Call Examples 237

Parameter Description

phoneNumber The phone number of the billing address.

Add Credit Card to New Address in Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"creditCardType\": \"visa\",\"creditCardNumber\":\"4111111111111111\",\"expirationMonth\": \"1\",\"expirationYear\":\"2020\",\"firstName\": \"John\",\"lastName\": \"Smith\",\"address1\":\"1 Main Street\",\"city\": \"cambridge\",\"state\": \"MA\",\"country\":\"USA\",\"postalCode\": \"02146\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CreateCreditCardActor/newCreditCardWithNewAddress"

Updating a Credit Card in an Order

The UpdateCreditCardActor is used to edit an existing credit card within an order. The path to this actor is: /

atg/commerce/custsvc/order/UpdateCreditCardActor.

This actor contains the updateCreditCard actor-chain:

Parameter Description

nickname The nickname of the credit card to update.

creditCardType The type of credit card to update.

creditCardNumber The credit card number to update.

expirationMonth The month that the credit card expires.

expirationYear The year that the credit card expires.

firstName The first name on the credit card.

middleName The middle name or initial on the credit card.

lastName The last name on the credit card.

address1 The first address field on the credit card.

address2 The second address field on the credit card.

city The city on the credit card.

state The state on the credit card.

country The country on the credit card.

postalCode The postal code on the credit card.

238 6 Internal REST MVC Service Call Examples

Parameter Description

phoneNumber A phone number associated with the credit card.

Update Credit Card in Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"nickname\" : \"visa 1111\", \"creditCardType\" : \"Visa\",\"creditCardNumber\" : \"4111111111111111\", \"expirationMonth\" : \"06\",\"expirationYear\" : \"2017\",\"firstName\":\"Charles\", \"middleName\":\"J\",\"lastName\":\"Smythe\",\"address1\":\"123 Main Street\", \"address2\":\"Suite 100\", \"city\":\"Cambridge\",\"state\":\"MA\", \"country\":\"USA\",\"postalCode\":\"02146\",\"phoneNumber\": \"617-637-8687\" }""http://localhost:8280/rest/model/atg/commerce/custsvc/order/UpdateCreditCardActor/updateCreditCard"

Assisting Customers with Orders

There are a number of REST services that have been created that allow agents to assist customers with orders.

Creating New Orders

The CreateNewOrderActor allows an agent to create a new order when working within a ticket. This

actor is located at /atg/commerce/custsvc/environment/CreateNewOrderActor, and contains the

createNewOrder actor-chain.

Parameter Description

doWarnings If set to true, will present a warning to the agent when leaving the

order they are currently working on and proceeding to the new order.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption If doTicketDispositionPrompt is selected, this provides a ticket

disposition option.

reasonCode If doTicketDispositionPrompt is selected, this provides a ticket

disposition reason code.

ticketNote Used to provide a note associated with the ticket.

publicNote Identifies if the ticket note is public.

6 Internal REST MVC Service Call Examples 239

New Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/environment/CreateNewOrderActor/createNewOrder"

The server response may be similar to the following:

{"currentOrder" : "02350008"}

Viewing the Current or Active Customer

The ActiveCustomerProfileActor is used to view the current, or active, customer. The path to this actor is: /

atg/userprofiling/ActiveCustomerProfileActor.

This actor contains the detailed actor-chain, which is used to view detailed information, and the summary

actor-chain, which is used to view summary information.

Parameters: None

View Current Customer Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/userprofiling/ActiveCustomerProfileActor/detailed"

Viewing the Customer Order History

The ServiceCustomerProfileActor is used to view the customer order history. The path to this actor is: /

atg/userprofiling/ServiceCustomerProfileActor.

This actor contains the detailed actor-chain.

Parameters: None

View Current Customer Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/userprofiling/ServiceCustomerProfileActor/detailed"

The server response may be similar to the following:

{"profile": { "middleName": null, "lastName": "Smith", "expressCheckout": false, "defaultCreditCard": null, "orderPriceLimit": null, "locale": null,

240 6 Internal REST MVC Service Call Examples

"currentLocation": "unknown", "id": "220022", "registrationDate": {"time": 1363218368049}, "email": "jsmith@example.com", "homeAddress": { "middleName": null, "lastName": "Smith", "item-id": null, "state": "MA", "address1": "1 Main Street", "address2": null, "address3": null, "companyName": null, "suffix": null, "repositoryId": "230024", "country": "USA", "city": "Cambridge", "faxNumber": null, "postalCode": "02046", "phoneNumber": "6176378687", "county": null, "prefix": null, "firstName": "John" }, "favoriteStores": [], "daytimeTelephoneNumber": null, "billingAddress": null, "login": null, "secondaryAddresses": {}, "purchaseLists": [], "firstName": "John", "shippingAddress": null, "allowPartialShipment": false, "creditCards": {"visa - 1111": { "id": "usercc10001", "expirationYear": "2022", "expirationMonth": "1", "creditCardNumber": "1111", "billingAddress": { "middleName": null, "lastName": "Smith", "item-id": null, "state": "MA", "address1": "One Main Street", "address2": null, "address3": null, "companyName": null, "suffix": null, "repositoryId": "230038", "country": "USA", "city": "Cambridge", "faxNumber": null, "postalCode": "02046", "phoneNumber": "6176378687", "county": null, "prefix": null, "firstName": "John" }, "creditCardType": "visa" }}

6 Internal REST MVC Service Call Examples 241

}}

Searching and Clearing Searches for an Order

The OrderSearchTreeQueryActor is used to search for orders. The path to this actor is: /atg/commerce/

custsvc/order/OrderSearchTreeQueryActor.

This actor contains the following actor-chains:

Actor-Chain Description

clearForm Clears the search session.

search Used to search for orders. It also indicates the way that the results will display,

including the paging and sort order.

The clearForm actor-chain allows you to clear the saved session search request.

Parameters: None

Clear Order Search Sessions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/OrderSearchTreeQueryActor/clearForm"

The search actor-chain searches for orders and configures the result display.

Parameter Description

fieldCount Indicates the size of the fields array, or the number of items in the field.

pageSize The number of orders per page. The default is set to 10.

pageNum Indicates which page of results to return. The default is set to 0.

maxResults The total number of search results to return. The default is set to 100.

docProps Identifies the properties of the order to return in each search result. The default

is set to all.

docSort The type of sort property to use. The default is strprop. Use numpropr if you

are doing a number property sort.

docSortOrder Sort the results in ascending or descending order. The default is

descending.

docSortProp The property to sort on. The default is id.

242 6 Internal REST MVC Service Call Examples

Parameter Description

saveRequest Keeps the request in session.

fields[].name The name of the order property to search.

fields[].op The operation, which should be set to starts.

field[].value The value that is used for searching this field.

Search for Orders Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{ \"pageNum\":1, \"pageSize\":3, \"fieldCount\":\"1\", \"fields\":{\"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-class-descriptor\" :{ \"atg-rest-values\" : {\"container-class\" : \"java.util.ArrayList\",\"element-class\":\"atg.textsearch.client.Field\"}}, \"atg-rest-values\":[{\"atg-rest-class-type\":\"atg.textsearch.client.Field\", \"name\": "id",\"op\":\"starts\",\"value\": \"x\"} ]}}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/OrderSearchTreeQueryActor/search"

The server response may be similar to the following:

{ "searchResponse": {"items": [ { "total": 715.2, "customerId": "se-570040", "returnedQuantity": 2, "status": "no_pending_action", "originOfOrder": "default", "submittedDate": "1340638926", "quantity": 4, "orderId": "xco20042" }, { "total": 316.7, "lastName": "Schmidt", "returnedQuantity": 5, "status": "no_pending_action", "originOfOrder": "default", "submittedDate": "1340638855", "quantity": 0, "firstName": "Stuart", "orderId": "xco20040" }, { "total": 88, "customerId": "se-570042", "returnedQuantity": 0, "status": "processing", "originOfOrder": "default", "submittedDate": "1340636993", "quantity": 2, "orderId": "xco20031"

6 Internal REST MVC Service Call Examples 243

} ]}, "pagesAvailable": 7}

Finding an Order by Order ID

The ViewOrderActor is used to find orders by ID. This actor also changes the currently viewed order. The path

to this actor is: atg/commerce/custsvc/order/ViewOrderActor.

This actor contains the changeViewOrder actor-chain:

Parameter Description

viewOrderId Identifies the order ID to use when finding the order.

Find Order By Order ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"viewOrderId\" : \"o99520001\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ViewOrderActor/changeViewOrder"

Selecting an Order to Work On

The ChangeOrderActor allows an agent to select an order and make it the current order in the Commerce

Service Center global context area. This enables an agent to work on the order and any associated tickets.

This actor uses the changeOrder actor-chain to obtain customer information. Additionally, this actor can

be configured to present ticket disposition information. This actor is located at: /atg/commerce/custsvc/

environment/ChangeOrderActor.

Parameter Description

customerId The ID of the customer to select.

doWarnings If set to true, will present a warning to the agent when leaving the

order they are currently working on and proceeding to the new order.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

dispositionOption If doTicketDispositionPrompt is selected, this provides a ticket

disposition option.

reasonCode If doTicketDispositionPrompt is selected, this provides a ticket

disposition reason code.

ticketNote Used to provide a note associated with the ticket.

244 6 Internal REST MVC Service Call Examples

Parameter Description

publicNote Identifies if the ticket note is public.

Select Order to Work On Example

This example confirms the ticket disposition, and displays any existing warnings.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"newOrderId\":\"o99810006\" \"doWarnings\":true, \"doTicketDispositionPrompt\":true, \"dispositionOption\":\"save\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/environment/ChangeOrderActor/changeOrder"

This example makes the changes to the order ticket disposition.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"newOrderId\":\"o99810006\" \"doWarnings\":false, \"doTicketDispositionPrompt\":false, \"doWarnings\":false, \"doTicketDispositionPrompt\":false, \"ticketNote\":\"Junk mail\", \"reasonCode\":\"spam\", \"dispositionOption\":\"close\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/environment/ChangeOrderActor/changeOrder"

The following may be response may occur from the server:

{ "allWarnings":["The current working order has items in it and has not been saved. If you continue, the order will be lost."}, "activeTIcketDisposition":false, "isDiscardable":true}

Cancelling or Deleting the Current Order

The CancelOrderActor is used to cancel or delete the current order. This actor is located in: /atg/commerce/

custsvc/order/CancelOrderActor.

This actor contains the cancelCurrentOrder actor-chain:

Parameter Description

orderIdToCancel The ID of the order to cancel.

Cancel Current Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{

6 Internal REST MVC Service Call Examples 245

\"orderIdToCancel\": \"o640001\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CancelOrderActor/cancelOrder"

Viewing Cross Sell Items in a Shopping Cart

The CSRCrossSellActor displays cross sell items in a shopping cart. It is located in: /atg/commerce/

custsvc/order/CSRCrossSellActor.

The crossSellItems actor-chain displays the products.

Parameters: None:

View Cross Sells Example

curl -v -b agent_cookies.txt "http://localhost:8180/rest/model/atg/commerce/custsvc/order/CSRCrossSellActor/crossSellItems"

The server response may be similar to the following:

{"crossSellItems": [ { "description": "Bring a little chateau to your palace", "largeImageUrl": "/crsdocroot/content/images/products/large/ ST_CamelotChair_large.jpg", "longDescription": "Feel like royalty with this dramatic accent chair. Constructed of solid oak with a rich finish, engraved designs and upholstered leather seat. Brass tack detailing adds to the overall design.", "isNavigableProduct": null, "mediumImageUrl": "/crsdocroot/content/images/products/medium/ ST_CamelotChair_medium.jpg", "fullImageUrl": "/crsdocroot/content/images/products/full/ ST_CamelotChair_full.jpg", "displayName": "Camelot Chair", "repositoryId": "xprod2037", "thumbnailImageUrl": "/crsdocroot/content/images/products/thumb/ ST_CamelotChair_thumb.jpg" }, { "description": "Tumbler glass great for mixed drinks and other beverages", "largeImageUrl": "/crsdocroot/content/images/products/large/ HOME_TumblerGlass_large.jpg", "longDescription": "Our heavy glass tumblers are a versatile addition to your barware collection. Holds 12 ounces. Dishwasher safe. Made in Poland.", "isNavigableProduct": null, "mediumImageUrl": "/crsdocroot/content/images/products/medium/ HOME_TumblerGlass_medium.jpg", "fullImageUrl": "/crsdocroot/content/images/products/full/ HOME_TumblerGlass_full.jpg", "displayName": "Tumbler Glass", "repositoryId": "xprod2085", "thumbnailImageUrl": "/crsdocroot/content/images/products/thumb/ HOME_TumblerGlass_thumb.jpg" },

246 6 Internal REST MVC Service Call Examples

{ "description": "Fine crystal tumbler for highballs and other beverages", "largeImageUrl": "/crsdocroot/content/images/products/large/ HOME_JackJillGlass_large.jpg", "longDescription": "This sturdy, sophisticated crystal glass adds an elegant touch. Perfect for entertaining and holiday use.", "isNavigableProduct": null, "mediumImageUrl": "/crsdocroot/content/images/products/medium/ HOME_JackJillGlass_medium.jpg", "fullImageUrl": "/crsdocroot/content/images/products/full/ HOME_JackJillGlass_full.jpg", "displayName": "Jack and Jill Glass Tumbler", "repositoryId": "xprod2074", "thumbnailImageUrl": "/crsdocroot/content/images/products/thumb/ HOME_JackJillGlass_thumb.jpg" }]}

Saving or Committing an Order

The CommitOrderActor saves or persists an order. It is located in: /atg/commerce/custsvc/

order/CommitOrderActor.

The CommitOrderActor has the following actor-chains:

Actor-Chain Description

persistOrder Saves the order..

commitOrder Commits the order.

sendConfirmationMessage Sends a confirmation message to an e-mail address. For information on

this actor-chain, refer to the Working with Scheduled Orders (page 253)

section.

validateTemplateOrder Validates a scheduled order template order. For information on this actor-

chain, refer to the Working with Scheduled Orders (page 253) section.

The persistOrder actor-chain saves the order

Parameters: None:

Save or Persist Order Example

curl -x 127.0.0.1:8888 -L -v -b agent_cookies.txt -H "Content-Type:application/json" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CommitOrderActor/persistOrder"

The commitOrder actor-chain commits an order and contains the following parameters:

6 Internal REST MVC Service Call Examples 247

Parameter Description

allowEmptyOrders This parameter allows you to commit empty orders.

salesChannel Identifies the sales channel used for this order.

siteId Identifies the site ID used for this order.

createTemplateFromSubmittedOrder Allows you to create a template from this submitted order.

Used for Scheduled Orders. Refer to the Working with

Scheduled Orders (page 253) section.

Commit Customer’s Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CommitOrderActor/commitOrder"

Confirming a Customer’s Order

The ConfirmOrderActor is used to confirm a customer’s order. As it does this, it re-prices the order one last

time before the agent commits the order to ensure that all pricing is up to date. The path to this actor is: /atg/

commerce/pricing/ConfirmOrderActor.

This actor contains the confirmOrder actor-chain.

Parameters: None

Confirm Customer’s Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/ConfirmOrderActor/confirmOrder"

The server response may be similar to the following:

{"order": { "lastModifiedTime": 1363214893776, "shippingGroupCount": 1, "paymentGroupCount": 0, "shippingGroups": [{ "specialInstructions": {}, "handlingInstructions": [], "state": 0, "locationId": null, "shippingMethod": "hardgoodShippingGroup", "id": "sg110016", "trackingNumber": null, "priceInfo": { "amount": 0, "currencyCode": "USD",

248 6 Internal REST MVC Service Call Examples

"amountIsFinal": false, "discounted": true, "rawShipping": 0 }, "description": "sg110016", "actualShipDate": null, "submittedDate": null, "shipOnDate": null, "shippingAddress": { "middleName": null, "lastName": null, "ownerId": null, "state": null, "address1": null, "address2": null, "address3": null, "companyName": null, "suffix": null, "city": null, "country": null, "id": null, "postalCode": null, "faxNumber": null, "phoneNumber": null, "county": null, "email": null, "prefix": null, "firstName": null, "jobTitle": null }, "stateDetail": null }], "commerceItems": [{ "id": "ci10000002", "productDisplayName": "Swiss Detail Clock", "returnedQuantity": 0, "priceInfo": { "amount": 99, "quantityDiscounted": 0, "discountable": true, "priceListId": "listPrices", "onSale": false, "rawTotalPrice": 99, "currencyCode": "USD", "amountIsFinal": false, "listPrice": 99, "discounted": false, "currentPriceDetailsSorted": [{ "amount": 99, "itemPriceInfo": null, "currencyCode": "USD", "tax": 0, "range": { "lowBound": 0, "class": "atg.core.util.Range", "highBound": 0, "size": 1 }, "amountIsFinal": false, "discounted": false,

6 Internal REST MVC Service Call Examples 249

"quantity": 1, "detailedUnitPrice": 99 }], "salePrice": 0 }, "catalogId": null, "quantity": 1, "catalogRefId": "xsku2011", "catalogKey": "en_US", "productId": "xprod2011" }], "id": "o110003", "siteId": "homeSite", "taxPriceInfo": { "amount": 0, "currencyCode": "USD", "countyTax": 0, "amountIsFinal": false, "countryTax": 0, "discounted": false, "stateTax": 0, "cityTax": 0, "districtTax": 0 }, "priceInfo": { "amount": 99, "total": 99, "shipping": 0, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": false, "manualAdjustmentTotal": 0, "rawSubtotal": 99, "discountAmount": 0 }, "paymentGroups": [], "profileId": "220022", "creationTime": 1363213904193, "relationships": [{ "id": "r100004", "amount": 0, "relationshipType": "SHIPPINGQUANTITY", "returnedQuantity": 0, "shippingGroupId": "sg110016", "commerceItemId": "ci10000002", "quantity": 1 }], "totalCommerceItemCount": 1}}

Sending a Customer Order Confirmation

The OrderConfirmationActor is referenced by the CommitOrderActor to display confirmation of a

successfully committed order. The path to this actor is/atg/commerce/order/purchase/

OrderConfirmationActor.

This actor contains the orderConfirmation actor-chain.

250 6 Internal REST MVC Service Call Examples

Parameters: None

Confirm Customer Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/OrderConfirmationActor/orderConfirmation"

The server response may be similar to the following:

{orderId: "0132", email: jsmith@example.com}

Modifying a Submitted Order

The ModifyOrderActor allows an agent to make a modification to a submitted order. The path to this actor is:

/atg/commerce/custsvc/environment/ModifyOrderActor.

This actor contains the modifySubmittedOrder actor-chain.

Parameter Description

orderID The ID of the order to be modified.

Modify a Submitted Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"orderID\" : \"o250005\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/environment/ModifyOrderActor/modifySubmittedOrder"

Submitting a Modified Order

The SubmitModifiedOrderActor enables an agent to re-submit an order that has been edited. The path to

this actor is: /atg/commerce/custsvc/environment/SubmitModifiedOrderActor.

This actor contains the submitModifiedOrder actor-chain.

Parameter Description

orderID The ID of the order to re-submit.

Submit a Modified Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d

6 Internal REST MVC Service Call Examples 251

"{ \"orderID\" : \"o250005\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/environment/SubmitModifiedOrderActor/submitModifiedOrder"

Duplicating an Order

The DuplicateOrderActor allows you to duplicate an existing order. When you duplicate the order, you can

duplicate the ticket disposition of the order. For additional information on working with ticket dispositions, refer

to the Working with Ticket Disposition Warnings and Messages (page 316) section. This actor is located at /

atg/commerce/custsvc/order/DuplicateOrderActor.

This actor uses the duplicateOrder actor-chain, which contains the following parameters:

Parameter Description

orderToDuplicate The ID of the scheduled order or scheduled order

item.

doWarnings If set to true, will present a warning to the agent

when proceeding to the new site.

doTicketDispositionPrompt If set to true, will present ticket disposition

prompts to the agent.

ticketDispositionOptions.dispositionOption If doTicketDispositionPrompt is enabled,

this provides a ticket disposition option.

ticketDispositionOptions.reasonCode If doTicketDispositionPrompt is selected,

this provides a ticket disposition reason code.

ticketDispositionOptions.ticketNote If doTicketDispositionPrompt is

selected,provides a note associated with the

ticket.

ticketDispositionOptions.publicNote If doTicketDispositionPrompt is selected,

identifies if the ticket note is public.

Duplicate an Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"orderToDuplicate\":\"xco30012\", \"doWarnings\":false,\"doTicketDispositionPrompt\":true, "dispositionOption":\"save\" }""http://localhost:8080/rest/model/atg/commerce/custsvc/order/DuplicateOrderActor/duplicateOrder"

Adding a Note to a Customer’s Current Order

The OrderNoteActor is used to add a note to a customer’s current order. The path to this actor is: /atg/

commerce/custsvc/order/.

252 6 Internal REST MVC Service Call Examples

This actor contains the addOrderNote actor-chain.

Parameter Description

comment The text of the note to add to the order.

Add Note to Current Order Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"comment\":\"Customer would like this in pink if it becomes available\" }""http://localhost:8180/rest/model/atg/commerce/custsvc/order/OrderNoteActor/addOrderNote"

Adding a Note to a Customer’s Original Order

The OriginalOrderNoteActor is used to add a note to a customer’s original order. The path to this actor is: /

atg/commerce/custsvc/order/OriginalOrderNoteActor.

This actor contains the addOrderNote actor-chain.

Parameter Description

comment The text of the note to add to the order.

Add Note to Original Order Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"comment\":\"Customer is ordering two different sizes and may return one\" }""http://localhost:8180/rest/model/atg/commerce/custsvc/order/OriginalOrderNoteActor/addOrderNote"

Creating a Quote for a Customer’s Order

The QuoteActor is used to submit a quote to a Business-to-Business customer. For information on integrating

with a third-party quoting system, refer to the Core Commerce Programming Guide. The path to this actor is: /

atg/commerce/order/purchase/QuoteActor.

This actor contains the completeQuote actor-chain.

6 Internal REST MVC Service Call Examples 253

Parameter Description

completeQuoteParameters This identifies the map and its string keys and values that provides

quote information.

Submitting a Quote Example

curl –L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{"orderId":"o10005", "completeQuoteParameters":{"atg-rest-class-type":"atg-rest-values":{"agentId":\"agent007\", "providerNote":\"Quote good until11/11/14\", "externalId":\"external001\", "expirationDate":\"2014-11-11 11:00\","orderAdjustment":\"5.0\"}}}" "http://localhost:8180/rest/model/atg/commerce/order/purchase/QuoteActor/completeQuote"

Working with Scheduled Orders

The following REST services allow agents to create and work with scheduled orders. For information on working

with scheduled orders, refer to the Core Commerce Programming Guide and the Commerce Service Center

Installation and Programming Guide. Note that before you can use these services, the active customer and order

must be set. To set the active customer, refer to the Viewing a Customer (page 202) section. To set the current

order, refer to the Selecting an Order to Work On (page 243) section. To commit and validate the order, refer to

the Saving or Committing an Order (page 246) section.

The CSRScheduledOrderActor is used to add scheduled orders. The path to this actor is: /atg/commerce/

custsvc/order/scheduled/CSRScheduledOrderActor.

This actor contains the following actor-chains:

Actor-Chain Description

createCSRScheduledOrder Used to create a new scheduled order.

updateCSRScheduledOrder Used to update a scheduled order.

Creating a Scheduled Order

The createCSRScheduledOrder actor-chain is used to create a scheduled order using the scheduled order

template.

Parameter Description

name The name of the scheduled order.

254 6 Internal REST MVC Service Call Examples

Parameter Description

scheduleType The type of scheduled order. Values can be either calendar or

interval.

startDate The start date used for the order.

endDateOption Options that can be set for the end date of the scheduled order. The

options include none, afterOccurrences or endBy.

numberOfOccurances This parameter is used with the afterOccurances option to calculate

the end date of the scheduled order.

endDate The end date of the scheduled order. Used with the endBy parameter.

daysOption This calendar property sets the delivery days of the scheduled order.

The options for this property are allDays, selectedDays and

selectedDates.

selectedDays An integer array of selected days, for example, “2,4” indicates Monday

and Wednesday. Values start at 1, indicating Sunday, and end with 7,

indicating Saturday.

selectedDates An integer array of values between 1 and 31.

occurrencesOption Identifies the occurrence of the scheduled order. Options are

allOccurrences or selectedOccurrences. Occurrences are

configurable when using selectedDays.

selectedOccurrences An integer array for occurrences of the scheduled order. Options are:

1 – First

2 – Second

3 – Third

4 – Fourth

5 – Last

Use this parameter with selectedDays to identify specific occurrences

within a month.

monthsOption Allows you to select specific months, selectedMonths, or to use all

months, allMonths, for the scheduled order.

selectedMonths Sets the delivery months of the scheduled orders. Values are 0 – 11,

which indicate January – December.

selectedHours Identifies the selected hours in an integer array. Values are 0 – 23, where

0 indicates 12:00, and 23 indicates 23:00 or 11:00 p.m.

selectedMinutes Identifies the selected minutes in an integer array. Values are 0 – 59.

selectedInterval Identifies the interval option for the schedule. Selected intervals are

used when creating a periodic schedule. When daysOption parameters

reference this parameter, it is used for creating calendar schedules.

6 Internal REST MVC Service Call Examples 255

Parameter Description

intervalOption Indicates the interval option, which is either weeks or days.

Selected intervals are used when creating a periodic schedule. When

daysOption parameters reference this parameter, it is used for creating

calendar schedules.

Create Scheduled Order Examples

The following example shows how you would create a schedule that runs every day, all month at a specific hour

and minute and then ends on a specific day:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"name\": \"Test endBy, allDays, allMonths\" , \"scheduleType\" :\"Calendar\" , \"startDate\" : \"03/10/2012\" , \"endDateOption\" : \"endBy\" ,\"numberOfOccurrances\" : 0 , \"endDate\" : \"03/12/2016\" , \"daysOption\" :\"allDays\" , \"selectedDays\" : \"0\" , \"selectedDates\" : \"0\" ,\"occurrencesOption\" : \"allOccurrences\" , \"selectedOccurrences\" : \"0\" ,\"monthsOption\" : \"allMonths\" , \"selectedMonths\" : \"0\", \"selectedHours\" :\"1,2,\" , \"selectedMinutes\" : \"0\" }" "http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderActor/createCSRScheduledOrder"

The following example shows how you could create a schedule that runs on selected dates in selected months

at a specific hour and time. This schedule is also set to end after 345 occurrences:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"name\" : \"T1 endA, selDatesMonths\" , \"scheduleType\" : \"Calendar\" ,\"startDate\" : \"03/10/2012\" , \"endDateOption\" : \"afterOccurrences\" ,\"numberOfOccurrances\" : 345 , \"endDate\" : \"03/12/2016\" , \"daysOption\" :\"selectedDates\" , \"selectedDates\" : \"1,3,28\" , \"monthsOption\" :\"selectedMonths\" , \"selectedMonths\" : \"1,3,11\", \"selectedHours\" :\"3,4,5,22\" , \"selectedMinutes\" : \"5,11,59\" }" "http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderActor/createCSRScheduledOrder"

The following example shows how you could create a schedule that runs on selected days within a specific

month at a specific hour and minute. This schedule has no end date:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"name\" : \"T2 endNo, selDaysMonths, allO\" , \"scheduleType\" : \"Calendar\", \"startDate\" : \"03/10/2012\" , \"endDateOption\" : \"none\" ,\"numberOfOccurrances\" : 0 , \"endDate\" : \"03/12/2016\" , \"daysOption\" :\"selectedDays\" , \"selectedDays\" : \"1,2,3,5,6,7\" , \"occurrencesOption\" :\"allOccurrences\" , \"monthsOption\" : \"selectedMonths\" , \"selectedMonths\" :\"4,5,6\", \"selectedHours\" : \"0,23\" , \"selectedMinutes\" : \"59\" }""http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderActor/createCSRScheduledOrder"

The following example shows how you could create a schedule that runs on the second and third Wednesdays

and the first, third and twenty-eight day of February at a specific hour and minute:

256 6 Internal REST MVC Service Call Examples

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"name\" : \"T3 endNo, selDaysMonths, 2n3rdWe\" , \"scheduleType\" :\"Calendar\" , \"startDate\" : \"03/10/2012\" , \"endDateOption\" : \"none\" ,\"daysOption\" : \"selectedDays\" , \"selectedDays\" : \"4\" , \"selectedDates\" :\"1,3,28\" , \"occurrencesOption\" : \"selectedOccurrences\" ,\"selectedOccurrences\" : \"2,3\" , \"monthsOption\" : \"selectedMonths\" ,\"selectedMonths\" : \"2\", \"selectedHours\" : \"12\" , \"selectedMinutes\" :\"0\" }" "http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderActor/createCSRScheduledOrder"

Updating a Scheduled Order

The updateCSRScheduledOrder actor-chain is used to update a scheduled order using a scheduled order

template.

Parameter Description

scheduledOrderId The repository ID of the scheduled order. Note, this is not the ID of the

scheduled order template, but the ID of the scheduled order item.

name The name of the scheduled order.

scheduleType The type of scheduled order. Values can be either calendar or

interval.

startDate The start date used for the order.

endDateOption Options that can be set for the end date of the scheduled order. The

options include none, afterOccurrences or endBy.

numberOfOccurances This parameter is used with the afterOccurances option to calculate

the end date of the scheduled order.

endDate The end date of the scheduled order. Used with the endBy parameter.

daysOption This calendar property sets the delivery days of the scheduled order.

The options for this property are allDays, selectedDays and

selectedDates.

selectedDays An integer array of selected days, for example, “2,4” indicate Monday

and Wednesday. Values start at 1, indicating Sunday, and end with 7,

indicating Saturday.

selectedDates An integer array of values between 1 and 31.

occurrencesOption Identifies the occurrence of the scheduled order. Options are

allOccurrences or selectedOccurrences. Occurrences are

configurable when using selectedDays.

6 Internal REST MVC Service Call Examples 257

Parameter Description

selectedOccurrences An integer array for occurrences of the scheduled order. Options are:

1 – First

2 – Second

3 – Third

4 – Fourth

5 – Last

Use this parameter with selectedDays to identify specific occurrences

within a month.

monthsOption Allows you to select specific months, selectedMonths, or to use all

months, allMonths, for the scheduled order.

selectedMonths Sets the delivery months of the scheduled orders. Values are 0 – 11,

which indicate January – December.

selectedHours Identifies the selected hours in an integer array. Values are 0 – 23, where

0 indicates 12:00, and 23 indicates 23:00 or 11:00 p.m.

selectedMinutes Identifies the selected minutes in an integer array. Values are 0 – 59.

selectedInterval Identifies the interval option for the schedule. Selected intervals are

used when creating a periodic schedule. When daysOption parameters

reference this parameter, it is used for creating calendar schedules.

intervalOption Indicates the interval option, which is either weeks or days.

Selected intervals are used when creating a periodic schedule. When

daysOption parameters reference this parameter, it is used for creating

calendar schedules.

Update Scheduled Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"scheduledOrderId\" : \"sco100002\" , \"name\" : \"Modified Company Schedule\" , \"selectedHours\" : \"12, 16, 20\" , \"selectedMinutes\" : \"05\" }""http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderActor/updateCSRScheduledOrder"

Submitting a Scheduled Order

The DuplicateAndSumbitActor is used to duplicate the scheduled order and immediately submit the order.

This actor is located at /atg/commerce/custsvc/order/scheduled/

DuplicateAndSubmitActor. Note that before you can submit a scheduled order, the active customer and

order must be set. To set the active customer, refer to the Viewing a Customer (page 202) section. To set the

current order, refer to the Selecting an Order to Work On (page 243) section.

This actor uses the duplicateAndSumbit actor-chain to identify the template of the scheduled order and then

submit it.

258 6 Internal REST MVC Service Call Examples

Parameter Description

orderToDuplicate The ID of the template scheduled order to immediately submit.

Submitting Scheduled Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"orderToDuplicate\":\"o100008\"}" "http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/DuplicateAndSubmitActor"

Activating a Scheduled Order

The ActivateScheduleActoris used to activate a scheduled order and initiate its schedule. This actor is

located at /atg/commerce/custsvc/order/scheduled/

activateScheduleActor.

This actor uses the activateSchedule actor-chain to identify and activate both the scheduled order and its

template.

Parameter Description

scheduledOrderId The ID of the scheduled order to activate.

orderId The ID of the template order with which the scheduled order is associated.

Activate Scheduled Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"orderId\":\"o100008\", \"scheduledOrderId\" : \"sco100002\"}""http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/ActivateScheduleActor/activateSchedule"

Deactivating a Scheduled Order

The DeactivateScheduleActor is used to deactivate a scheduled order and terminate its schedule. This actor

is located at /atg/commerce/custsvc/order/scheduled/

DeactivateScheduleActor.

This actor uses the deactivateSchedule actor-chain to identify and activate both the scheduled order and its

template.

6 Internal REST MVC Service Call Examples 259

Parameter Description

scheduledOrderId The ID of the scheduled order to deactivate.

orderId The ID of the template order with which the scheduled order is associated.

Deactivate Scheduled Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"orderId\":\"o100008\", \"scheduledOrderId\" : \"sco100002\"}""http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/DeactivateScheduleActor/deactivateSchedule"

Displaying Scheduled Order Details

The CSRScheduledOrderInfoActor is used to display the details of a scheduled order once a scheduled order

action has occurred. This actor is located at /atg/commerce/custsvc/order/scheduled/

CSRScheduledOrderInfoActor.

Note: The CSRScheduledOrderInfoActor must be used alongside other Commerce Service Center scheduled

order actions. Calling this actor directly produces no results.

The CSRScheduledOrderInfoActor contains the following actor-chains:

Actor-Chain Description

getReadableSchedule Used to display the readable details of a scheduled order.

getAllScheduledOrderInfo Used to display all information of a scheduled order.

The getReadableSchedule actor-chain displays the scheduled order details. This actor-chain is used by other

actors and actor-chains to obtain data regarding scheduled orders. It has the following parameters:

Parameter Description

scheduledOrderId The ID of the scheduled order or scheduled order item.

scheduledOrder The ID of the template order with which the scheduled order is associated.

locale The locale used to display the output.

Display Readable Scheduled Order Detail Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d

260 6 Internal REST MVC Service Call Examples

"{ \"locale\" : \"en_GB\" , \"scheduledOrderId\" : \"sco90002\" }"http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderInfoActor/getReadableSchedule"

The getAllScheduleInfo actor-chain displays the scheduled order details. This actor-chain is used by other

actors and actor-chains and returns only the scheduled object.

Parameter Description

scheduledOrderId The ID of the scheduled order or scheduled order item.

scheduledOrder The ID of the template order with which the scheduled order is associated.

locale The locale used to display the output.

Display All Scheduled Order Detail Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"locale\" : \"en_GB\" , \"scheduledOrderId\" : \"sco90002\" }"http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderInfoActor/getAllScheduleInfo"

Displaying Scheduled Order Confirmation

The CSRScheduledOrderConfirmationActor is referenced by the CSRScheduledOrderActor,

ActiveScheduleActor and DeactivateScheduleActor to display information once a scheduled order

action has occurred. Note that this actor is invoked by other actors working on the current order. Calling this

actor directly will display no results.

The CSRScheduledOrderConfirmationActor contains the scheduledOrderConfirmation actor-chain,

which provides the scheduled order details that confirm success of a specific action, such as creating or

activating a scheduled order.

Parameters: None

Display Scheduled Order Confirmation Example

curl –L –v -b agent_cookies.txt -H "Content-Type: application/json"http://localhost:8181/rest/model/atg/commerce/custsvc/order/scheduled/CSRScheduledOrderConfirmationActor/scheduledOrderConfirmation"

Working with Scheduled Order Templates

The CommitOrderActor is used to work with scheduled order templates. The path to this actor is: /atg/

commerce/custsvc/order/CommitOrderActor.

6 Internal REST MVC Service Call Examples 261

This actor contains the following actor-chains for working with template orders:

Actor-Chain Description

commitOrder Commits a scheduled order template from a submitted order.

validateTemplateOrder Validates the scheduled order template.

sendCOnfirmationMessage Allows you to send an order confirmation e-mail.

Creating a Template from a Scheduled Order

The commitOrder actor-chain is used to create a template order from a submitted scheduled order. This service

call requires that the order has been successfully submit.

Parameter Description

allowEmptyOrders Indicates if empty orders will be permitted in the order.

salesChannel Identifies the sales channel for this order.

siteId Identifies the site ID for this order.

createTemplateFromSubmittedOrder Indicates if a scheduled order template should be created

from this submitted order.

Create Template from Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"createTemplateFromSubmittedOrder\" : \"true\"}" "http://localhost:8080/rest/model/atg/commerce/custsvc/order/CommitOrderActor/commitOrder"

Validating a Scheduled Order Template

The validateTemplateOrder actor-chain is a service call that validates a template order.

Parameters: None

Validate Scheduled Order Template Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/order/CommitOrderActor/validateTemplateOrder"

262 6 Internal REST MVC Service Call Examples

Sending E-Mail Confirmation for a Scheduled Order Template

The sendConfirmationMessage actor-chain allows you to manually send a confirmation e-mail for a specific

scheduled order template.

Parameter Description

email The e-mail address, obtained from the customer’s profile. If an e-mail parameter is not

passed in, the e-mail address of the current customer will be used by default.

templateName The name of the template. If no template name is provided, the template name that is

set on the confirmation object is used.

Send Manual E-Mail Confirmation Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"templateName" : \"NEW_ORDER\",\"email\" : \"jsmith@example.com\" }""http://localhost:8080/rest/model/atg/commerce/custsvc/order/CommitOrderActor/sendConfirmationMessage"

Identifying a Template Order

The IsScheduledOrderTemplateActor is a service call that identifies if a schedule order is a scheduled

order template. This actor is located at /atg/commerce/custsvc/order/scheduled/ and contains the

isCurrentOrderScheduledOrderTemplate actor-chain.

Parameters: None

Create Template from Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/order/scheduled/IsScheduledOrderTemplateActor/isCurrentOrderScheduledOrderTemplate"

Reviewing a Template

The ScheduledOrderLookupActor allows you to iterate through a list of scheduled orders for a specific

customer, or other parameter. This actor is located at /atg/commerce/order/scheduled/

ScheduledOrderLookup and uses the scheduledOrderLookup actor-chain.

This actor-chain contains the following parameters. Note that you need to provide only one parameter as the

system cycles through all available parameters. If you include more than one parameter, the extra parameters

will be ignored. :

6 Internal REST MVC Service Call Examples 263

Parameter Description

itemId The ID of the of the item.

templateId The ID of the template.

profileId The ID of the user’s profile.

siteIds The IDs of the sites used in this scheduled order.

siteScope The site scope used in this scheduled order.

Review a Template’s Schedule Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"profileId" : \"se-570098\" }" "http://localhost:8080/rest/model/atg/commerce/order/scheduled/ScheduledOrderLookupActor/scheduledOrderLookup"

Viewing a Template Order List of Submitted Orders

The SubmittedOrderTableActor allows you to view a list of the submitted orders applied to a template

order. Note that this call requires the orderID of a submitted order. It is located at /atg/commerce/order/

scheduled/SubmittedOrderTableActor.

This actor uses the list actor-chain:

Parameter Description

orderId The ID of the of the submitted order.

sortDirection The way in which you want to sort the list.

sortField The field used to sort the list.

currentPage The paging results of the search to display.

resultsPerPage The number of results to display per page.

View a Template’s List of Submitted Orders Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"orderId" : \"o1233241\" }" "http://localhost:8080/rest/model/atg/commerce/order/scheduled/SubmittedOrderTableActor/list"

The results may be similar to the following:

264 6 Internal REST MVC Service Call Examples

{ "searchResults": [{ "id": "o500035" }, { "id": "o500030" }, { "id": "o500001" }, { "id": "o490001" }, { "id": "o480006" }, { "id": "o480001" }, { "id": "o120006" }, { "id": "o110003" }, { "id": "o90007" }, { "id": "o90003" }], "resultsPerPage": 10, "totalItemCount": 10, "currentPage": 0}

Viewing a User’s List of Template Orders

The ScheduledOrderTableActor allows you to view a list of the submitted orders for a specific user. It is

located at /atg/commerce/order/scheduled/ScheduledOrderTableActor.

This actor uses the list actor-chain:

Parameter Description

profileId The ID of the of the user’s profile.

sortDirection The way in which you want to sort the list.

sortField The field used to sort the list.

currentPage The paging results of the search to display.

resultsPerPage The number of results to display per page.

6 Internal REST MVC Service Call Examples 265

View a User’s List of Scheduled Orders Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"orderId" : \"o1233241\" }" "http://localhost:8080/rest/model/atg/commerce/order/scheduled/ScheduledOrderTableActor/list"

The results may be similar to the following:

{ "searchResults": [{ "id": "o120008" }], "resultsPerPage": 10, "totalItemCount": 1, "currentPage": 0}

Adjusting Customer’s Orders

The following REST services allow an agent to make manual price adjustments to an order, and to initiate a price

override.

The ManualAdjustmentsActor is used to make a price adjustment to a customer’s order. The path to this actor

is: /atg/commerce/custsvc/order/ManualAdjustmentsActor.

This actor contains the following actor-chains:

Actor-Chain Description

addAdjustment Used to issue a manual adjustment to an order.

deleteAdjustment Used to delete an adjustment from an order.

viewAdjustmentLimits Used to view the adjustment limits for an order.

viewReasonCodes Used to return the reason for an adjustment.

Adjusting a Customer’s Order

The addAdjustment actor-chain is used to issue an adjustment to a customer’s order.

Parameter Description

adjustmentAmount The amount of the adjustment.

266 6 Internal REST MVC Service Call Examples

Parameter Description

adjustmentNote A note to provide a description for the adjustment.

adjustmentReasonCode The adjustment reason code used for this adjustment.

adjustmentType The type of adjustment.

Adjust Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"adjustmentAmount\" : \"10\", \"adjustmentReasonCode\" : \"Appeasement\",\"adjustmentNote\" : \"Customer ordered 10 of these last week\", \"adjustmentType\" : \"amountOff\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ManualAdjustmentsActor/addAdjustment"

Deleting an Adjustment from a Customer’s Order

This actor contains the deleteAdjustment actor-chain. It is used to delete an existing adjustment from an

order.

Parameter Description

adjustmentId The ID of the adjustment.

adjustmentReasonCode The adjustment reason code used for this adjustment.

Delete Order Adjustment Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"adjustmentId\" : \"700001\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ManualAdjustmentsActor/deleteAdjustment"

Overriding an Item’s Price in the Customer’s Order

The CartModifierActor contains the setOrderByCommerceId actor-chain that allows an agent to override

the price of an item within an order.

To override a price, add the following to the URL:

IPO:commerceItemId=newPrice

6 Internal REST MVC Service Call Examples 267

Override Price Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrderByCommerceId?ci172000006=1&IPO:ci172000006=19.99"

Viewing the Adjustment Limits

This actor contains the viewAdjustmentLimits actor-chain. It is used to view the adjustment limits for an

order.

Parameters: None

View Adjustment Limits Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" http://localhost:8080/rest/model/atg/commerce/custsvc/order/ManualAdjustmentsActor/viewAdjustmentLimits?atg-rest-output=json"

Viewing the Reason Code for an Adjustment

This actor contains the viewReasonCodes actor-chain. It is used to view the reason for which an adjustment

was applied.

Parameters: None

View Reason Codes Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" http://localhost:8080/rest/model/atg/commerce/custsvc/order/ManualAdjustmentsActor/viewReasonCodes?atg-rest-output=json"

Assisting Customers with Catalogs

The ProductCatalogActor is used to get catalog and product information. The path to this actor is:

/atg/commerce/custsvc/catalog/ProductCatalogActor.

This actor contains the following actor-chains:

Actor-Chain Description

getCurrentCatalogRootCategories Obtains the user’s current catalog and root categories.

268 6 Internal REST MVC Service Call Examples

Actor-Chain Description

getCategory Displays the user’s sub-categories.

getProduct Views a product by Product ID.

Getting the Customer’s Current Catalog

The getCurrentCatalogRootCategories actor-chain obtains the current catalog.

Parameters: None

Get Current Catalog Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/catalog/ProductCatalogActor/getCurrentCatalogRootCategories"

The server response might be:

{"rootCategories": [ { "id": "homeStoreNonNavigableProducts", "description": "", "defaultParentCategory": null, "displayName": "Non Navigable Products", "type": null }, { "id": "homeStoreRootCategory", "description": null, "defaultParentCategory": null, "displayName": "Home Store Root", "type": null }]}

Browsing the Customer’s Catalog By Category ID

The getCatagory actor-chain allows the agent to browse the customer’s current catalog by category ID.

Parameter Description

categoryId The ID of the category.

filterBySite Identifies if the product is contained in the current site, and if so filters by site.

filterByCatalog Identifies if the product is contained in the current site, and if so filters by catalog.

6 Internal REST MVC Service Call Examples 269

Browse by Catalog ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"categoryId\" : \"cat50056\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/catalog/ProductCatalogActor/getCategory"

Browsing the Customer’s Catalog By Product ID

The getProduct actor-chain allows the agent to browse the customer’s current catalog and to look up products

by their ID.

Parameter Description

productId The ID of the product.

filterBySite Identifies if the product is contained in the current site, and if so filters by site.

filterByCatalog Identifies if the product is contained in the current site, and if so filters by catalog.

siteIds The site associated with the catalog.

catalogs Identifies the catalogs to browse.

Get Product by Product ID Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"productId\" : \"xprod1047\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/catalog/ProductCatalogActor/getProduct"

Searching for Catalogs with Criteria

The MoreCatalogsSearchActor allows an agent to search for specific catalogs. This actor uses the

catalogSearch actor-chain, and is located at /atg/commerce/custsvc/catalog/

MoreCatalogsSearchActor.

The catalogSearch actor-chain uses the following parameters:

Parameter Description

resultSetSize Sets the number of results that are displayed per page. The default is 10.

keyword The keyeword used to search the catalogs.

startDate Optional. The start date used to search the catalogs. For example, YYYY-MM-DD

HH:MM:SS format, or, 2010-08-11 00:00:00.

270 6 Internal REST MVC Service Call Examples

Parameter Description

endDate Optional. The end date used to search the catalogs. For example, YYYY-MM-DD

HH:MM:SS format, or, 2010-08-11 00:00:00.

allowEmptySearch When this parameter is set to true, if there is no search criteria, all catalogs will be

searched.

Search Catalog Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"keyword\" : \"Store\", \"startDate\" : \"2009-09-28 00:00:00\",\"endDate\" : \"2013-03-12 15:39:59\"}" "http://localhost:8080/rest/model/atg/commerce/custsvc/catalog/MoreCatalogsSearchActor/catalogSearch"

Working with the Current Catalog

The EnvironmentChangeActor allows an agent to work with the current catalog. The path to this actor is: /

atg/commerce/custsvc/environment/EnvironmentChangeActor.

This actor contains the following catalog actor-chains:

Actor-Chain Description

setCurrentCatalog Selects a catalog and makes it the current catalog.

getCurrentCatalog Retrieves the user’s current catalog.

setDefaultCatalog Resets the user’s default catalog

Selecting a Current Catalog

The setCurrentCatalog actor-chain allows an agent to select a catalog and make it the current catalog.

Parameter Description

catalogId The ID of the catalog to find.

Select Catalog Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"-d "{\"catalogId\" : \"homeStoreCatalog\"}" "http://localhost:8080/rest/model/

6 Internal REST MVC Service Call Examples 271

atg/commerce/custsvc/environment/EnvironmentChangeActor/setCurrentCatalog"

Retrieving the Current Catalog

The getCurrentCatalog actor-chain retrieves the user’s current catalog.

Parameters: None

Retrieve Current Catalog Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/environment/EnvironmentChangeActor/getCurrentCatalog"

Resetting the Current Catalog

The setDefaultCatalog actor-chain resets the user’s current default catalog.

Parameters: None

Reset Current Catalog Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/environment/EnvironmentChangeActor/setDefaultCatalog"

Obtaining Product Prices

The PricingActor is used to obtain prices for products using product IDs or SKU IDs. The path to this actor is: /

atg/commerce/pricing.

This actor contains the following actor-chains:

Actor-Chain Description

productPriceRanges Provides the lowest and highest sale price for a product. These prices are

obtained from the user’s profile.

skuPrices Displays either the listPrice and salePrice for a specific SKU if price

lists are enabled. If price lists are not enabled, displays both listPrice and

salePrice.

Getting Price Ranges for a Product

The productPriceRanges actor-chain returns the lowest and highest prices for a specific product. It uses the

following parameters:

272 6 Internal REST MVC Service Call Examples

Parameter Description

productId Identifies the product ID to use.

Get Prices by Range ID Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"productId\" : \"xprod2085\"}" "http://localhost:8280/rest/model/atg/commerce/pricing/PricingActor/productPriceRanges"

The server response may be similar to the following:

{"highestSalePrice": 19, "lowestSalePrice": 19, }

Obtaining List Price and Sale Prices for a Product by SKU

The skuPrices actor-chain returns the list and sale prices for a specific product using its SKU ID. It uses the

following parameters:

Parameter Description

productId Identifies the product ID to use.

skuId The SKU ID to use.

Obtain Prices by Product ID Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"skuId\" : \"xsku2085\"}" "http://localhost:8280/rest/model/atg/commerce/pricing/PricingActor/skuPrices"

The server response may be similar to the following:

{"listPrice": 19, "salePrice": 19,}

Working with Customer’s Price Lists

The EnvironmentChangeActor also allows an agent to work with the current price lists. The path to this actor

is: /atg/commerce/custsvc/environment/EnvironmentChangeActor.

6 Internal REST MVC Service Call Examples 273

This actor contains the following price list actor-chains:

Actor-Chain Description

setCurrentPriceList Selects a price list and makes it the current price list.

getCurrentPriceList Retrieves the user’s current price list.

setDefaultPriceList Resets the user’s default price list.

Selecting a Current Price List

The setCurrentPriceList actor-chain allows an agent to select a price list and make it the current price list.

Parameter Description

priceListId The ID of the price list to find.

Select Price List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"-d "{\"priceListId\" : \"salePrices\"}" "http://localhost:8080/rest/model/atg/commerce/custsvc/environment/EnvironmentChangeActor/setCurrentPriceList"

Retrieving the Current Price List

The getCurrentPriceList actor-chain retrieves the user’s current price list.

Parameters: None

Retrieve Current Price List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/environment/EnvironmentChangeActor/getCurrentPriceList"

Resetting the Current Price List

The setDefaultPriceList actor-chain resets the user’s current default price list.

Parameters: None

274 6 Internal REST MVC Service Call Examples

Reset Current Price List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/environment/EnvironmentChangeActor/setDefaultPriceList"

Searching for a Price List

The PriceListSearchActor allows an agent to search for a price list. It is located at /atg/commerce/

custsvc/pricing/pricelists/PriceListSearchActor and uses the priceListSearch actor-chain.

Parameter Description

resultSetSize Allows you to set the number of the results displayed on the page. The

default is 10.

keyword The keyword used to search

startDate Specifies the start date of a search date range. For example, YYYY-MM-DD

HH:MM:SS format, or, 2010-08-11 00:00:00.

endDate Specifies the end date of a search date range. For example, YYYY-MM-DD

HH:MM:SS format, or, 2010-08-11 00:00:00.

allowEmptySearch When set to true, this parameter allows you to search without using a search

criteria.

Search Price List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"keyword\" : \"sale\", \"startDate\" : \"2000-09-28 00:00:00\", \"endDate\" :\"2013-03-12 15:39:59\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/pricing/priceLists/PriceListSearchActor/priceListSearch"

Working with Customer’s Promotions

The PromotionWalletActor is used to work with customer’s promotion information. The path to this actor is:

/atg/commerce/custsvc/promotion/PromotionWalletActor.

This actor contains the following actor-chains:

6 Internal REST MVC Service Call Examples 275

Actor-Chain Description

getAvailablePromotions Obtains the available promotions.

updatePrice Updates the price of the order.

grantPromotion Add a promotion.

unGrantPromotion This chain allows an agent to remove an agent-granted promotion.

includePromotionInOrder This chain is used to add promotions that are presented by the

promotions wallet.

excludePromotionFromOrder This chain is used to ignore promotions that are presented by the

promotions wallet.

saveWallet Saves the promotion wallet.

revertWallet Reverts the order before promotions were included.

Getting Available Promotions

The getAvailablePromotions actor-chain returns a list of promotions that can be used.

Parameter Description

resultsPerPage Identifies the number of promotions that will be displayed on the page.

Get Available Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"resultSetSize\" : 20 }" "http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/getAvailablePromotions"

The response may be similar to the following:

{"availablePromotions":[ { "ignored":false, "agentGranted":false, "closenessQualifiers":[], "close":false, "considered":false, "discount":0, "promotionId":"promo10003", "usable":true, "promotionName":"CRS Home - Free Shipping", "applied":true, "active":false,

276 6 Internal REST MVC Service Call Examples

"promotionStateId":"80" }, { "ignored":false, "agentGranted":false, "closenessQualifiers":[ { "id":"se-200005", "name":"Save $10 on all orders over $100" } ], "close":true, "considered":false, "discount":0, "promotionId":"promo50012", "usable":true, "promotionName":"$10 off Orders over $100", "applied":false, "active":false, "promotionStateId":"82" }]}

Updating Prices After Promotions

The updatePrice actor-chain returns an updated price of the customer’s order.

Parameters: None

Update Order with Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/updatePrice"

Adding a Promotion

The grantPromotion actor-chain adds a promotion to the order. This actor-chain has the following parameters:

Parameter Description

promotionId The ID of the promotion to be granted.

Add Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"promotionId\": \"promoto20010\" }" "http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/unGrantPromotion"

6 Internal REST MVC Service Call Examples 277

Removing a Promotion

The unGrantPromotion actor-chain removes a promotion from the order. In Commerce Service Center, only

agent-granted promotions can be removed by agents. This actor-chain has the following parameters:

Parameter Description

promotionStateId The ID of the state of promotion to be granted.

Remove Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"promotionStateId\": \"92\" }" "http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/unGrantPromotion"

Include Promotions from Wallet

The includePromotionInOrder actor-chain adds a promotion from the promotions wallet. This actor-chain

has the following parameters:

Parameter Description

promotionId The ID of promotion to be added.

Include Promotion Wallet Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"promotionId\": \"promo20010\" }" "http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/includePromotionInOrder"

Ignoring Promotions from Wallet

The excludePromotionFromOrder actor-chain excludes promotions that may be added to the order from the

promotions wallet. This actor-chain has the following parameters:

Parameter Description

promotionId The ID of promotion to be ignored.

278 6 Internal REST MVC Service Call Examples

Ignore Promotion Wallet Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"promotionId\": \"promo20010\" }" "http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/excludePromotionInOrder"

Saving the Promotions Wallet

The saveWallet actor-chain saves the promotions wallet.

Parameters: None

Save Promotions Wallet Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/saveWallet"

Reverting the Promotions Wallet

The revertWallet actor-chain reverts to the last saved version of the promotions wallet.

Parameters: None

Revert Promotions Wallet Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionWalletActor/revertWallet"

Obtaining Closeness Qualifiers

The ClosenessQualifierActor enables an agent to view how close a customer is to qualifying for a

promotion. This actor is located at /atg/commerce/custsvc/promotion/

ClosenessQualifierActor, and contains the getClosenessQualifiers actor-chain.

Parameters: None

Obtain Closeness Qualifiers Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/ClosenessQualifierActor/getClosenessQualifiers"

The response may be similar to the following:

{"closenessQualifiers":[ {"id":"se-200005",

6 Internal REST MVC Service Call Examples 279

"name":"Save $10 on all orders over $100"}]}

Searching for Promotions

The PromotionsSearchActor enables an agent to search for a promotion. This actor is located at /atg/

commerce/custsvc/promotion/PromotionSearchActor, and contains the searchPromotions actor-

chain.

Parameter Description

keyword The keyword used to search for promotions.

dateOption The date to search for the promotion. This parameter can take the following

values: Today, Start in Next 7 Days, End in Last 7

Days, All Future, or All Expired.

type The type of promotion to search for. This parameter can take the following

values: " empty, which gets all types, Item Discount, Order

Discount, or Shipping Discount.

hideGlobal To hide global discounts, set this parameter to true.

site Which sites to search for promotions. This parameter can take the following

values: " empty, which gets all sites or site name.

resultsSetSize The number of promotion results to display.

Search Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"keyword\" : \"10\", \"dateOption\" : \"Today\", \"type\" : \"\" ,\"hideGlobal\" : \"true\", \"site\" : \"\", \"resultSetSize\" : 20}""http://localhost:8080/rest/model/atg/commerce/custsvc/promotion/PromotionSearchActor/searchPromotions"

The response may be similar to the following:

{"searchResults":[ { "id":"abandonedOrderDiscount", "displayName":"10% off Order" }, { "id":"promo20011", "displayName":"TENSHIP Coupon - 10% Off Order" }]}

280 6 Internal REST MVC Service Call Examples

Adding Store Credit

The AddStoreCreditActor allows an agent to add store credit to a profile. The profile must be active before

the agent can issue a credit. Refer to Selecting a Customer to Work On (page 208). This actor is located at /

atg/commerce/custsvc/profile/AddStoreCreditActor and uses the addStoreCredit actor-chain with

the following parameters:

Parameter Description

amount The amount of the credit.

comments Any comments regarding the credit.

Store Credit Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"amount\" : \"10\", \"comments\" : \"Loyalty Customer – Added $10 credit\" }""http://localhost:8180/rest/model/atg/commerce/custsvc/profile/AddStoreCreditActor/addStoreCredit"

Displaying Lost Promotions

The LostPromotionsActor displays a list of promotions that a customer loses during the returns and

exchanges process. Note that this data is not saved and can only be retrieved during the return and exchange

process. This actor is located at /atg/commerce/custsvc/returns/LostPromotionsActor. It contains the

promotionsLost actor-chain.

Parameters: None

Display Lost Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/returns/LostPromotionsActor/promotionsLost"

The response may be similar to the following:

{"promotionsLost":"promo50012"}

Displaying Changed Promotions

The CSRReturnsActor uses the changePromotions actor-chain to display a list of promotions that change

when items are returned or exchanged from a shipped order. This call returns a list of promotion IDs and display

names. The path to this actor is: /atg/commerce/custsvc/returns/

CSRReturnsActor.

6 Internal REST MVC Service Call Examples 281

Parameters: None

Display Changed Promotions Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/catalogs/CSRReturnsActor/changedPromotions"

The response may be similar to the following:

{\"ChangedPromotions\": { \"id\" : \"promo50012\", \"displayName\" : \"10 offorders over $100\" }

Working with Customer’s Gift Lists

The following actors are used to work with a customer’s gift or wish list. For information on adding a gift or wish

list item to a shopping cart, refer to Add Item From Customer’s Gift List Example (page 220) and Add Item

From Customer’s Wish List Example (page 221).

The CSRGiftlistActor contains several actor-chains that initiate gift list actions. The path for this actor is /

atg/commerce/custsvc/gifts/.

This actor contains the following actor-chains:

Actor-Chain Description

createGiftlist Creates a gift or wish list.

updateGiftlist Updates a gift or wish list.

addItemToGiftlist Adds an item to a gift list.

removeItemFromGiftlist Removes an item from a gift list.

addItemToWishlist Adds an item to a wish list.

removeItemFromWishlist Removes an item from a wish list.

moveItemsFromCart Removes a gift or wish list item from the Shopping Cart.

deleteGiftlist Deletes a gift or wish list.

Creating a Customer’s Gift or Wish List

The createGiftlist actor-chain creates a gift list or a wish list.

282 6 Internal REST MVC Service Call Examples

Note: The following parameters are all optional, unless stated otherwise.

Parameter Description

isPublished Identifies if the list has been published.

siteId The ID of the site.

eventName Required. The name of the gift list event.

eventDate Required. The date of the gift list event.

eventType Required. The type of the gift list event.

description A description of the gift list.

comments Any comments that are included with the list.

shippingAddressId The ID of the shipping address.

instructions Any instructions that are included with the list.

isNewAddress Identifies if the address included in this list is new.

firstName The first name of the customer.

middleName The middle name or initial of the customer.

lastName The last name of the customer.

address1 The first address field of the customer.

address2 The second address field of the customer.

city The city of the customer’s address.

state The state or province of the customer’s address.

postalCode The postal code of the customer’s address.

country The country of the customer’s address.

phoneNumber The phone number associated with the customer.

Basic Create Gift List Example

This example uses only the required parameters.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"eventName\" : \"Wedding\", \"eventType\": \"Wedding\", \"eventDate\" :\"AUG 30, 2013\" }" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/createGiftlist"

6 Internal REST MVC Service Call Examples 283

Create Gift List with Existing Address Example

This example uses an existing customer address. The address is identified by the shippingAddressId

parameter.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"eventName\" : \"Birthday\", \"eventType\": \"Birthday\", \"eventDate\" :\"NOV 10, 2013\",\"shippingAddressId\" : \"270015\" }" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/createGiftlist"

Create Gift List with New Address Example

This example creates a new customer address.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"eventName\" : \"Valentines\", \"eventType\": \"Other\", \"eventDate\" :\"FEB 14, 2014\",\"isNewAddress\" : \"true\", \"firstName\":\"Tara\",\"lastName\":\"Hammond\", \"middleName\":\"C\", \"address1\":"\101 First St\",\"address2\":null, \"city\":\"Cambridge\",\"state\":\"MA\",\"country\":\"USA\",\"postalCode\": \"02146\", \"phoneNumber\":\"617-637-8687\" }""http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/createGiftlist"

Updating a Customer’s Gift or Wish List

The updateGiftlist actor-chain allows an agent to edit a customer’s gift or wish list.

Note: The following parameters are all optional, unless stated otherwise.

Parameter Description

isPublished Identifies if the list has been published.

siteId The ID of the site.

eventName Required. The name of the gift list event.

eventDate Required. The date of the gift list event.

eventType Required. The type of the gift list event.

description A description of the gift list.

comments Any comments that are included with the list.

shippingAddressId The ID of the shipping address.

instructions Any instructions that are included with the list.

isNewAddress Identifies if the address included in this list is new.

firstName The first name of the customer.

284 6 Internal REST MVC Service Call Examples

Parameter Description

middleName The middle name or initial of the customer.

lastName The last name of the customer.

address1 The first address field of the customer.

address2 The second address field of the customer.

city The city of the customer’s address.

state The state or province of the customer’s address.

postalCode The postal code of the customer’s address.

country The country of the customer’s address.

phoneNumber The phone number associated with the customer.

Update Customer Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl240010\", \"eventName\" : \"St Patricks Day\", \"eventType\":\"Other\",\"description\": \"Things needed for St Patrick's Day\", \"eventDate\" :\"MAR 17, 2013\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/updateGiftlist"

Adding Items to a Customer’s Gift List

The addItemToGiftlist actor-chain allows an agent to add an item to a customer’s gift list.

Parameter Description

giftlistId The ID of the gift list.

quantity The quantity of the products to add to the gift list.

productId The product ID of the product to add to the gift list.

catalogRefIds The catalog reference ID of the product being added to the gift list.

siteId The ID of the site.

Add Item to Customer Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{

6 Internal REST MVC Service Call Examples 285

\"giftlistId\": \"gl380011\", \"productId\": \"xprod1015\", \"catalogRefIds\" :\"xsku1043\",\"quantity\": \"2\", \"siteId\": \"homeSite\"}""http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/addItemToGiftlist"

Adding Items to a Customer’s Wish List

The addItemToWishlist actor-chain allows an agent to add an item to the active customer’s wish list.

Parameter Description

siteId The ID of the site.

quantity The quantity of the products to add to the wish list.

productId The product ID of the product to add to the wish list.

catalogRefIds The catalog reference ID of the product being added to the wish list.

Add Item to Customer’s Wish List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"productId\": \"xprod2085\", \"catalogRefId\" : \"xsku2085\", \"quantity\":\"1\", \"siteId\":\"homeSite\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/addItemToWishlist"

Removing Items from a Customer’s Gift List

The removeItemFromGiftlist actor-chain allows an agent to remove an item from a customer’s gift list.

Parameter Description

giftlistId The ID of the gift list from which the items will be removed.

giftitemId The ID of the item to remove from the gift list.

Remove Item from Customer’s Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl380011\", \"giftItemId\" : \"gi30002\"}""http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/removeItemFromGiftlist"

286 6 Internal REST MVC Service Call Examples

Removing Items from a Customer’s Wish List

The removeItemFromWishlist actor-chain enables an agent to remove an item from a customer’s wish list.

Parameter Description

giftitemId The ID of the items to be removed from the wish list.

Remove Item from Customer’s Wish List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftItemId\" : \"gi30001\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/removeItemFromWishlist"

Moving Items to a Gift or Wish List from a Customer’s Shopping Cart

The moveItemsFromCart actor-chain allows an agent to take an item from a shopping cart and move it into the

specified gift or wish list. You can specify a default quantity for an item, or specify the quantity for a specific item.

Parameter Description

giftlistId The ID of the gift or wish list to which the items will be moved.

itemIds The IDs of the items to move to the list.

quantity The quantity of the items to move to the list.

Move Item to Gift or Wish List from Customer’s Cart Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\" : \"gl620010\", \"itemIds\": \"ci42000001\"}""http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/moveItemsFromCart?ci42000001=6"

Deleting a Customer’s Gift List

The deleteGiftlist actor-chain allows an agent to delete a specific gift list.

Parameter Description

giftlistId The ID of the gift or wish list to delete.

6 Internal REST MVC Service Call Examples 287

Delete a Customer’s Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\": \"gl220010\" }" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/deleteGiftlist"

Viewing a Customer’s Gift List

The GiftlistLookupActor enables an agent to view a customer’s gift or wish list. This actor is located at: /

atg/commerce/gifts/GiftlistLookupActor, and contains the following actor-chains.

Actor-Chain Description

view Views the ID of the customer’s gift or wish list.

giftlistItems Displays the items within the gift list.

The view actor-chain contains the following parameter:

Parameter Description

giftlistId The ID of the gift or wish list to view.

View Gift List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftListId\" : \"gl430003\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/view"

The server response may be similar to the following:

{"giftlist": { "giftlistItems": [], "instructions": null, "description": null, "name": "Valentines", "public": true, "date": {"time": 1360816200000}, "type": "Other", "repositoryId": "gl130271", "addressId": "230324", }}

288 6 Internal REST MVC Service Call Examples

The giftlistItems actor-chain contains the following parameter:

Parameter Description

giftlistId The ID of the gift or wish list to view.

View Gift List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftListId\" : \"gl430003\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/giftlistItems"

Viewing a Customer’s Wish List

The ServiceCustomerProfileActor enables an agent to view a customer’s gift or wish list. This actor is

located at /atg/userprofiling/ServiceCustomerProfileActor, and contains the viewWishlist actor-

chain.

Parameters: None

View Gift or Wish List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/userprofiling/ServiceCustomerProfileActor/viewWishlist"

Searching for a Customer’s Gift List

The CSRGgiftlistSearchActor is used to find a customer’s gift list. This actor is located at /atg/commerce/

gifts/ and contains the search actor-chain.

Parameter Description

firstName The first name of the customer.

lastName The last name of the customer.

eventType The list event type.

eventDate The list event date.

sortField Indicates the field used to sort the results.

sortDirection Indicates the direction that the results are sorted.

6 Internal REST MVC Service Call Examples 289

Parameter Description

resultsPerPage The number of results that are displayed per page.

currentPage The paging results of the search to display.

Search for Customer Gift List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"firstName\" : \"Stuart\", \"lastName\" : \"Schmidt\", \"eventType\": \"Other\",\"eventDate\" : \"AUG 30, 2013\", \"sortDirection\": \"desc\", \"sortField\" :\"eventName\",\"currentPage\": 1, \"resultsPerPage\": 5 }" "http://localhost:8180/rest/model/atg/commerce/gifts/CSRGiftlistSearchActor/search"

The server response may be similar to the following:

{"giftlists": [ { "giftlistItems": [], "instructions": null, "description": null, "name": "Birthday", "public": true, "date": {"time": 1377837000000}, "type": "Other", "repositoryId": "gl140010", "addressId": null }, { "giftlistItems": [{ "siteId": "storeSiteUS", "skuId": "xsku1043", "quantity": 2, "repositoryId": "gi50001", "productId": "xprod1015" }], "instructions": null, "description": null, "name": "updated test", "public": true, "date": {"time": 1377837000000}, "type": "Other", "repositoryId": "gl120010", "addressId": null }, { "giftlistItems": [], "instructions": null, "description": null, "name": "Anniversary", "public": true, "date": {"time": 1377837000000}, "type": "Other", "repositoryId": "gl120011", "addressId": null

290 6 Internal REST MVC Service Call Examples

}]}

Viewing a List of Customer’s Gift or Wish Lists

The GiftlistTableActor allows an agent to display a list of all of the customer’s gift or wish lists. This actor is

located at /atg/commerce/custsvc/gifts/GiftlistTableActor, and contains the list actor-chain.

Parameter Description

doOwnerSearch This Boolean parameter, if set to true, restricts search results to the

current customer.

doSiteFilterSearch Filter sites when searching.

includeDisabledSites Include disabled sites in the view.

sortDirection Indicates the direction that the results are sorted.

sortField Indicates the field used to sort the results.

resultsPerPage The number of results that are displayed per page.

currentPage The paging results of the search to display.

View Customer List of Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"doOwnerSearch\" : false, \"doSiteFilterSearch\": false,\"includeDisabledSites\" : false, \"sortDirection\": \"desc\", \"sortField\" :\"eventName\", \"currentPage\": 1, \"resultsPerPage\": 5 }""http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/GiftlistTableActor/list"

A possible server response might be:

{ "resultsPerPage": 10, "totalItemCount": 1, "currentPage": 0, "giftlists": [{ "giftlistItems": [], "instructions": null, "description": null, "name": null, "public": true, "date": {"time": 1364308351415}, "type": null,

6 Internal REST MVC Service Call Examples 291

"repositoryId": "gl130274" "addressId": "230327" }]}

Assisting Customers with In-Store Pickup

The REST MVC service calls that agents use to assist customer with in-store pickup are similar to the external-

based REST calls. Refer to the Working with In-Store Pickup (page 176) section for actor-chains and parameters.

When agents initiate these REST calls, their session will use the agent_cookies.txt file.

Agent Search for Store Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"distance\" : \"10\", \"skuId\" : \"sku30029\"}" "http://localhost:8280/rest/model/atg/commerce/locations/StoreLocatorActor/locateItems"

Agent Display In-Store Search Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"pageNum\" : \"2\"}" "http://localhost:8280/rest/model/atg/commerce/locations/StoreLocatorActor/currentResultPageNum"

For information on adding an item to an in-store pickup, refer to Adding Items to a Customer’s Shopping

Cart (page 220).

Working with Approvals

The REST MVC Web service calls allow agents or supervisors to view, approve or reject order modifications. For

information on approvals in Commerce Service Center, refer to the Commerce Service Center User Guide

Finding Pending Approvals

The ViewAllPendingApprovalsActor allows an agent or supervisor to find orders that are waiting for

approval before fulfillment. This actor contains the viewAllPendingApprovals actor-chain. This actor is

located at /atg/commerce/custsvc/approvals/ViewAllPendingApprovalsActor.

Parameters: None

Find Pending Approvals Example

curl \-L \-v \-c agent_cookies.txt \-H "Content-Type: application/json"

292 6 Internal REST MVC Service Call Examples

"http://localhost:8180/rest/model/atg/commerce/custsvc/approvals/ViewAllPendingApprovalsActor/viewAllPendingApprovals"

The response may be similar to the following:

"pendingApprovals": { "creationDate": { "time": 1364378657000 }, "customerId": "210006", "orderTotal": 13.75, "appeasementTotal": -12, "agentId": "a10001", "customerEmail": "customer@example.com", "orderId": "o1200001" }, { "creationDate": { "time": 1364378689000 }, "customerId": "210006", "orderTotal": 18.75, "appeasementTotal": -12, "agentId": "a10001", "customerEmail": "customer@example.com", "orderId": "o1200002" }

Approving or Rejecting a Pending Order

The ApproveOrderActor is used to approve or reject any order that is waiting for authorization. This actor is

located at /atg/commerce/custsvc/approvals/order/ApproveOrderActor, and contains the following

actor-chains:

Actor-Chain Description

approveOrder Approves a pending order.

rejectOrder Rejects a pending order.

The approveOrder actor-chain allows an agent or supervisor to approve a pending order.

Parameter Description

approvalId The ID of the approval.

6 Internal REST MVC Service Call Examples 293

Parameter Description

newOrderId The ID of the order that has been approved.

Approve Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"newOrderId\": \"o650008\",\"approvalId\": \"400003\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/approvals/order/ApproveOrderActor/approveOrder"

The rejectOrder actor-chain allows an agent or supervisor to reject a pending order.

Parameter Description

approvalId The ID of the approval.

newOrderId The ID of the order that has been rejected.

Reject Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{ \"newOrderId\": \"o650008\",\"approvalId\": \"400003\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/approbals/order/ApproveOrderActor/rejectOrder"

Assisting the Customer with Returns and Exchanges

The returns and exchange process allows an agent to assist a customer when returning and/or exchanging an

item.

Returns and Exchange Process Overview

When an agent initiates a return and exchange process, the workflow process may be similar to the following:

1. The return or exchange process is initiated by calling the createReturn actor-chain. This actor-chain

generates a shippinGroupsList itemList as a list of all of the possible items that can be returned from an

order.

2. Return codes for items to be returned and/or exchanged are obtained by calling the returnReasons actor

chain.

3. The process continues by calling the selectItems actor chain, which passes in the updated

shippingGroupList and return reason codes.

294 6 Internal REST MVC Service Call Examples

4. From this point, there are a number of actions that can be performed, depending on the requirements of the

returns and exchange process.

• Obtain the list of refund methods that can be used to provide the customer with a refund by calling the

modifiableRefundsMethodList actor-chain. By default, this amount is credited back to the original

credit card.

• Modify the default amounts that are credited to the refund methods by calling the applyRefunds actor-

chain.

• Modify the default refund amounts by calling the ModifyRefundValuesActor.

• Display any promotions that are lost as part of a return or an exchange by calling the

LostPromotionsActor. Note that this data is calculated when the actor is called, but the data is not

saved.

• Display any promotions that have been changed as part of the return or exchange process by calling the

changePromotions actor-chain.

5. To complete the return or exchange process, use the confirmReturn actor-chain to confirm that the

item should be returned or exchanged. The confirmation chain can be customized to display different

confirmation details.

6. Once the return or exchange process is complete, you can process items when they have been received back

from the customer by calling the receiveReturnItems actor-chain, and display return history for a specific

order by calling the returnsHistory actor-chain.

The CSRReturnsActor is used when working with returns and exchanges. This actor, along with the

ModifyRefundValuesActor, and the LostPromotionsActor, comprise the agent-based returns and

exchanges functionality. The path to this actor is: atg/commerce/custsvc/returns/

CSRReturnsActor.

This actor contains the following actor-chains:

Actor-Chain Description

createReturn Initiates the return request.

selectItems Adds items to the return request.

confirmReturn Displays confirmation of the return request.

confirmation Displays the return/exchange details to confirm that the return was

successful.

cancelReturnRequest Cancels the return request.

returnReasons Obtains the return reason codes for the request.

receiveReturnItems Displays the details of the items selected for return.

modifiableRefundsMethodList Retrieves a list of all methods to which a refund can be applied.

applyRefunds Applies a refund type and value to the order.

6 Internal REST MVC Service Call Examples 295

Actor-Chain Description

isCurrentOrderReturnable Identifies if the current order is returnable

isItemReturnable Identifies if items within the order are returnable.

isReturnActive Determines if there is a return in process for this order.

returnsHistory Displays the return history of this order

returns Displays the order’s return request.

nonReturnItemDetails Displays refund adjustments that were applied to non-return items.

changedPromotions Identifies promotions that have changed during the return process.

For information on this actor-chain, refer to the Displaying Changed

Promotions (page 280) section.

Creating a Return

The createReturn actor-chain initiates a return request specific to the order ID passed in and sets

the Commerce Service Center environment settings, such as price lists. Note that this actor-chain calls

the StartReturnExchangeProcess form handler. The external createReturn actor-chain uses the

ReturnFormHandler. For information on the external createReturn actor-chain, refer to the Initiating a

Return (page 158) section. Subsequent Return REST calls use this return request for the order specific return

details. It contains the following parameters:

Parameter Description

newOrderId The ID of the order to be returned.

Initiate Returns and Exchanges Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"newOrderId\":\"xco30045\"}" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/createReturn"

The server response may be similar to the following:

{ "returnRequest":{ "shippingGroupList":[ { "shippingPriceRaw":18.95, "shippingMethod":"Next Day", "shippingGroupId":"xcsg20080", "itemList":[ {

296 6 Internal REST MVC Service Call Examples

"returnItemId":"xcr10101", "quantityShipped":1, "quantityReturned":0, "quantityAvailable":1, "description":"Boyfriend Jeans", "commerceItemId":"xci1000051", "catalogRefId":"xsku2519_2" }, { "returnItemId":"xcr10102", "quantityShipped":1, "quantityReturned":0, "quantityAvailable":1, "description":"Corduroy Cargo Pants", "commerceItemId":"xci1000052", "catalogRefId":"xsku2512_2" }, { "returnItemId":"xcr10103", "quantityShipped":1, "quantityReturned":0, "quantityAvailable":1, "description":"Huey Martini Glass", "commerceItemId":"xci1000053", "catalogRefId":"xsku2076" } ], "shippingAddress":{ "lastName":"Robinson", "state":"NY", "address1":"604 Red Mountain Road", "address2":null, "country":"US", "city":"Rochester", "postalCode":"14603", "phoneNumber":"212-555-8885", "email":null, "firstName":"Adrian" } } ], "orderCurrencyCode":"USD", "orderId":"xco30045" }}

Adding Items to a Return Request

The selectItems actor-chain identifies the items that will be returned in the current return request. This

actor-chain, which requires that the createReturn actor-chain is called first, takes the input from an updated

JSON-formatted return request and then uses that input to set the server-side shipping group list’s return item

values. Note that you must update the shippingGroupList items to set the number of items to be returned

or exchanged, and the reason code. Refer to the Obtaining Return Reason Codes (page 299) section for

information on retrieving reason codes.

This actor-chain contains the following parameters:

6 Internal REST MVC Service Call Examples 297

Parameter Description

processName Identifies if the process is a return or an exchange.

jsonReturnRequest Identifies the updated JSON-formatted return request

where the item to be returned or exchanged in the

shippingGroupList.itemList has been updated

so that either the quantityToReturn property or the

quantityToExchange property is greater than 0, and the

returnReasoncode is set.

Add Items to Return Example

The following is a JSON-based example:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"processName\":\"Return\",\"jsonReturnRequest\":{\"returnRequest\":{\"shippingGroupList\":[{\"itemList\":[{\"id\":\"xcr10101\",\"shippingGroupId\":\"xcsg20080\",\"quantityToReturn\":1,\"returnReason\":\"didNotLike\",\"quantityToExchange\":0},{\"id\":\"xcr10102\",\"shippingGroupId\":\"xcsg20080\",\"quantityToReturn\":1,\"returnReason\":\"defective\",\"quantityToExchange\":0}]}]}}}" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/selectItems"

The following is an XML-based example:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/xml" –d"<parameters><jsonReturnRequest>{"returnRequest":{"shippingGroupList":[{"itemList":[{"id":"xcr10101","shippingGroupId":"xcsg20080","quantityToReturn":1,"returnReason":"didNotLike","quantityToExchange":0},{"id":"xcr10102","shippingGroupId":"xcsg20080","quantityToReturn":1,"returnReason":"defective","quantityToExchange":0}]}]}}</jsonReturnRequest><processName>Return</processName></parameters>" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/selectItems"

The server response may be similar to the following:

{ "returnRequest":{ "returnPaymentState":"Refund", "otherRefund":0, "requestId":null, "state":"incomplete", "processName":"Return", "actualShippingRefund":12.62, "replacementOrderId":null, "originatingOrderId":"xco30045", "exchangeProcess":false, "returnAdjustedOrderId":"o350068", "orderCurrencyCode":"USD", "refundMethodList":[ { "refundType":"creditCard",

298 6 Internal REST MVC Service Call Examples

"amount":113.62, "maximumRefundAmount":131.85 }, { "refundType":"storeCredit", "amount":0, "maximumRefundAmount":-1 } ], "returnItemCount":2, "actualTaxRefund":0, "returnItemList":[ { "quantityToExchange":0, "suggestedTaxRefundShare":0, "quantityReceived":0, "itemCurrencyCode":"USD", "returnItemId":"xcr10101", "actualTaxRefundShare":0, "refundAmount":50.52, "shippingGroupId":"xcsg20080", "quantityReturned":0, "quantityShipped":1, "quantityAvailable":1, "description":"Boyfriend Jeans", "quantityToReturn":1, "actualShippingRefundShare":6.31, "suggestedShippingRefundShare":6.31, "commerceItemId":"xci1000051", "catalogRefId":"xsku2519_2", "suggestedRefundAmount":50.52, "disposition":null, "returnReason":"didNotLike" }, { "quantityToExchange":0, "suggestedTaxRefundShare":0, "quantityReceived":0, "itemCurrencyCode":"USD", "returnItemId":"xcr10102", "actualTaxRefundShare":0, "refundAmount":51.44, "shippingGroupId":"xcsg20080", "quantityReturned":0, "quantityShipped":1, "quantityAvailable":1, "description":"Corduroy Cargo Pants", "quantityToReturn":1, "actualShippingRefundShare":6.31, "suggestedShippingRefundShare":6.31, "commerceItemId":"xci1000052", "catalogRefId":"xsku2512_2", "suggestedRefundAmount":51.44, "disposition":null, "returnReason":"defective" } ], "processImmediately":false, "rma":null, "returnFee":0,

6 Internal REST MVC Service Call Examples 299

"orderId":"xco30045", "profile":{ "middleName":null, "lastName":"Smith", "id":"se-570085", "login":"jsmith@example.com", "firstName":"Joe" } }}

Obtaining Return Reason Codes

The returnReasons actor-chain displays a list of all reason codes. Reason codes can be used in the

selectItem actor-chain as outlined in Adding Items to a Return Request (page 296).

Parameters: None

Obtain Return Reason Codes Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/returnReasons"

The server may return a response similar to the following:

{ "reasons": { "incorrectSize": "Incorrect Size", "incorrectColor": "Incorrect Color", "didNotMeetExpectations": "Did Not Meet Expectations", "didNotLike": "Did Not Like", "defective": "Defective", "incorrectItem": "Incorrect Item" }}

Confirming a Return Request

The confirmReturn actor-chain allows you to submit and process a return request, and displays confirmation

detail if a submission is successful.

Parameters: None

Confirm Return Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8181/rest/model/atg/commerce/custsvc/returns/ReturnActor/confirmReturn"

300 6 Internal REST MVC Service Call Examples

Displaying Return Request Confirmation Details

The confirmation actor-chain is an informational actor-chain used to display return details confirming that the

return was successful. You can use this actor-chain to display return data as part of the confirmReturn actor-

chain output. This actor-chain outputs the confirmation e-mail address. To display other information, such as

the exchange order ID, you must customize this call to hold a reference to the return request. Refer to the ATG

Platform API Reference for information on customizing this actor-chain.

Note that this actor is invoked by the confirmReturn actor-chain. Calling this actor directly will display no

results.

Cancelling a Return Request

The cancelReturnRequest actor-chain cancels a return request at any point during the returns process.

Parameters: None

Cancel Return Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/cancelReturnRequest"

Receiving Return Items

The receiveReturnItems actor-chain is used to get information about the items that have been selected to

be returned and to process the items that have been returned as received. This actor-chain uses the following

parameters:

Parameter Description

returnItemsRequest The received item’s return request, where the key is the

return item ID and the value is the return request ID.

returnItemDispositions The item disposition information contained within the

return request.

receiveItemQuantities The quantity of the return items received.

Receive Return Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"returnItemsRequests\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\": {\"xc4400016\":\"xc4400011\"}}, \"returnItemDispositions\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\":{\"xc4400016\":\"defective\"}}, \"receiveItemQuantities\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\"

6 Internal REST MVC Service Call Examples 301

:{\"xc4400016\":1}}}" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/receiveReturnItems"

Retrieving Available Refund Methods

The modifiableRefundsMethodList actor-chain retrieves the sorted list of all credit and payment methods

to which a refund can be applied, and the default values for the item to be returned. This does not display any

extra store credit that might be displayed due to an exchange. Note that this call should be run after running the

selectItems actor-chain.

Parameters: None

Refund Methods Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8181/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/modifiableRefundsMethodList"

The server response may be similar to the following:

{ "modifiableRefundMethodList": [{ "refundType": "creditCard", "amount": 51.31 }]}

Applying Refunds

The applyRefunds actor-chain is used to apply refund type and value to the order. The server-side

sortedRefundMethodList is updated by the UI with the values of the amounts passed in, in the order

in which they are passed in. As such, the inputs for the applyRefund actor-chain should match the

sortedRefundMethodList.

Parameter Description

returnMethodListSize The array size to retrieve from the JSP. The array size corresponds to the

number of refund methods available.

Applying Refund Values Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"items\":{\"atg-rest-class-type\":\"java.util.ArrayList\",\"atg-rest-values\":[{\"atg-rest-class-type\":\"atg.commerce.csr.returns.RefundMethod\",\"amount\":\"46.31\"},{\"atg-rest-class-type\":

302 6 Internal REST MVC Service Call Examples

\"atg.commerce.csr.returns.RefundMethod\",\"amount\":\"5.00\"}]},\"returnMethodListSize\" : \"2\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/applyRefunds"

Displaying Return History

The returnHistory actor-chain displays the return history and contains the following parameters:

Parameter Description

orderId The ID of the order to be returned.

Customer Return History Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"orderId\":\"o2620001\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/returnHistory"

Identifying if the Order is Returnable

The isCurrentOrderReturnable actor chain looks at the current order to see if it is a returnable order. It

provides a true or false server response.

Parameters: None

Is Order Returnable Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/order/CSRReturnsActor/isCurrentOrderReturnable"

Identifying if an Item is Returnable

The isItemReturnable actor-chain looks at an item within a current order to see if it is returnable. If the item is

returnable, the returnable state is ITEM_RETURNABLE. If the returnable state contains anything else, the item is

not returnable.

This actor-chain uses the following parameter:

Parameter Description

commerceItemId The ID of the item.

6 Internal REST MVC Service Call Examples 303

Is Item Returnable Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"commerceItemId\":\"xci1000070\"}" "http://localhost:8181/rest/model/atg/commerce/custsvc/order/CSRReturnsActor/isItemReturnable"

Identifying if the Order Contains an Active Return

The isReturnActive actor-chain determines if you are in the middle of a return process by looking at the

current order to see if it is associated with an active return. It provides a true or false server response.

Parameters: None

Does Order Contain Active Return Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/order/CSRReturnsActor/isReturnActive"

Reviewing Details of Returned Items

The returns actor-chain provides details of returned items in the current order and contains the following

parameters:

Parameter Description

orderId The ID of the order.

Does Order Contain Active Return Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"orderId\" : \"xco20040\"}""http://localhost:8180/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/returns"

The server output may resemble the following:

{ "itemReturnSummary":{ "xci1000071":2, "xci1000070":1, "xci1000073":1, "xci1000072":1 }, "resultName":[

304 6 Internal REST MVC Service Call Examples

{ "methods":[ { "methodType":"creditCard" } ], "requestId":"xc100005", "replacementOrderId":null, "items":[ { "requestId":"xc100005", "returnItemId":"xc100007" }, { "requestId":"xc100005", "returnItemId":"xc100008" }, { "requestId":"xc100005", "returnItemId":"xc100010" }, { "requestId":"xc100005", "returnItemId":"xc100009" } ], "rma":"xc100005", "createdDateTime":1340764006000, "orderId":"xco20040" } ]}

Displaying Non-Return Items

The nonReturnItemDetails actor-chain displays any non-returned items that have been affected by the

return. When working on a current order, when a return is completed, the system displays the refund details

with non-returnable items, as well as the refund types and any additional notes. The return is then submitted for

completion. Note that this call will produce information only after selectItems is called, and if the items being

returned affect non-returned items.

Parameters: None

Complete Return Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"http://localhost:8180/rest/model/atg/commerce/custsvc/returns/CSRReturnsActor/nonReturnItemDetails"

Updating a Credit Card for a Returns

The UpdateCreditCardActor is used to edit an existing credit card for a return. The path to this actor is: /atg/

commerce/order/purchase/UpdateCreditCardActor.

6 Internal REST MVC Service Call Examples 305

This actor contains the updateCreditCardForReturns actor-chain. This actor-chain depends on the

ReturnsActor createReturn actor-chain to obtain the correct information.

Parameter Description

creditCardType The type of credit card.

creditCardNumber The credit card number.

expirationMonth The month that the credit card expires.

expirationYear The year that the credit card expires.

firstName The first name on the credit card.

middleName The middle name or initial on the credit card.

lastName The last name on the credit card.

address1 The first address field on the credit card.

address2 The second address field on the credit card.

city The city on the credit card.

state The state on the credit card.

country The country on the credit card.

postalCode The postal code on the credit card.

phoneNumber A phone number associated with the credit card.

Update Credit Card Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d"{\"paymentGroupId\":\"pg3980014\",\"creditCardType\":\"visa\",\"creditCardNumber\": \"4111111111111111\",\"expirationMonth\":\"1\",\"expirationYear\": \"2017\"}" "http://localhost:8181/rest/model/atg/commerce/custsvc/order/UpdateCreditCardActor/updateCreditCardForReturns"

Applying Appeasements to a Customer’s Order

An appeasement is a goodwill credit that can be applied to a fulfilled order where a customer has experienced

difficulties but does not wish to return or exchange the items. When you issue an appeasement to a customer

you can issue it against the cost of the items in the order, or against the cost of shipping associated with the

order.

306 6 Internal REST MVC Service Call Examples

Initiating an Appeasement

The initiateAppeasement actor-chain initiates a return request specific to the order ID passed in and sets

the Commerce Service Center environment settings, such as price lists. Note that this actor-chain calls the

InitiateAppeasementFormHandler form handler.

Parameter Description

newOrderId The ID of the order to which the appeasement applies.

Initiate Appeasement Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"newOrderId\" : \"xco30076\"}" http://localhost:8080/rest/model/atg/commerce/custsvc/appeasement/AppeasementActor/initiateAppeasement?atg-rest-output=json"

Applying an Appeasement

The applyAppeasementRefunds actor-chain is used to apply appeasement type and value to the order. Note

that this actor-chain calls the AppeasementFormHandler form handler.

Parameter Description

appeasementType This is the type of appeasement.

appeasementAmount This is the value of the appeasement.

reasonCode This is the reason for the appeasement.

appeasementNotes This is any notes by the agent to support the appeasement.

Apply Appeasement Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"appeasementType\" : \"items\", \"appeasementAmount\" : \"5\", \"reasonCode\" : \"orderArrivedLate\", \"appeasementNotes\" : \"test notes value\", }" http://localhost:8080/rest/model/atg/commerce/custsvc/appeasement/AppeasementActor/applyAppeasementRefunds?atg-rest-output=json"

Validating an Appeasement

The ValidateAppeasementValues actor-chain is used to validate the refund total and the refund amounts

allocated to different payment options. Note that this actor-chain calls the AppeasementFormHandler form

handler.

6 Internal REST MVC Service Call Examples 307

Parameters: None

Validate Appeasement Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" http://localhost:8080/rest/model/atg/commerce/custsvc/appeasement/AppeasementActor/validateAppeasementValues?atg-rest-output=json"

Submitting an Appeasement

The submitAppeasement actor-chain is used to submit the appeasement. Note that this actor-chain calls the

AppeasementFormHandler form handler.

Parameters: None

Submit Appeasement Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" http://localhost:8080/rest/model/atg/commerce/custsvc/appeasement/AppeasementActor/submitAppeasement?atg-rest-output=json"

Cancelling an Appeasement

The cancelAppeasement actor-chain is used to cancel the appeasement. Note that this actor-chain calls the

AppeasementFormHandler form handler.

Parameters: None

Cancel Appeasement Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" http://localhost:8080/rest/model/atg/commerce/custsvc/appeasement/AppeasementActor/cancelAppeasement?atg-rest-output=json"

Sending a Confirmation Message for an Appeasement

The sendConfirmationMessage actor-chain is used to send a confirmation message regarding the

appeasement indicating whether it was successfully completed, or if it is awaiting approval. Note that this actor-

chain calls the AppeasementFormHandler form handler.

Parameters: None

Send Confirmation Message Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" http://localhost:8080/rest/model/atg/commerce/custsvc/appeasement/AppeasementActor/sendConfirmationMessage?atg-rest-output=json"

308 6 Internal REST MVC Service Call Examples

Approving an Appeasement

The approveAppeasement actor-chain is used to approve an appeasement where the value

of the appeasement exceeds the agent’s authorized limit. Note that this actor-chain calls the

AppeasementApprovalFormHandler form handler.

Parameter Description

approvalId The ID of the approval request.

Approve Appeasement Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"approvalId\" : \"200001\"}" http://localhost:8080/rest/model/atg/commerce/custsvc/approvals/appeasement/AppeasementApprovalsActor/approveAppeasement?atg-rest-output=json"

Rejecting an Appeasement

The RejectAppeasement actor-chain is used to reject an appeasement where the value of the appeasement

exceeds the agent’s authorized limit. Note that this actor-chain calls the AppeasementApprovalFormHandler

form handler.

Parameter Description

approvalId The ID of the approval request.

Initiate Appeasement Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"rejectApprovalId\" : \"200001\"}" http://localhost:8080/rest/model/atg/commerce/custsvc/approvals/appeasement/AppeasementApprovalsActor/rejectAppeasement?atg-rest-output=json"

Modifying Refund Values

The ModifyRefundValuesActor is used to edit the values of refunded items. This actor is dependent on the

createReturn and selectItems actor-chains, which should be called first. This actor produces no output, but

can be customized as needed. The path to this actor is /atg/commerce/custsvc/returns. This actor contains

the following actor-chains:

6 Internal REST MVC Service Call Examples 309

Actor-Chain Description

modifyRefundValues This service allows you to edit the values of a refunded item within an

array.

resetRefundValues This service call clears and resets all refund values. You can use this

property to edit the default refund value for a returned item, shipping

cost or other adjustment.

Modify a Refund Value

The modifyRefundValues actor-chain allows you to edit the values of a refund item.

Parameter Description

returnItemRefunds A map of the returned items and their corresopnding refunds.

shippingAdjustment Identifies shipping adjustments made for the refund.

otherAdjustment Identifies any other adjustments made for the refund.

Modify Refund Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{\"returnItemRefunds\":{\"atg-rest-class-type\":\"java.util.HashMap\",\"atg-rest-values\":{\"0\":\"-50.52\"}}, \"shippingAdjustment\" : \"-6.31\",\"otherAdjustment\" : \"0\" }" http://localhost:8180/rest/model/atg/commerce/custsvc/returns/ModifyRefundValuesActor/modifyRefundValues"

Resetting a Refund Value

The resetRefundValues actor-chain allows you to clear and reset all of the values of a refund item to their

default values.

Parameters: None

Reset Refund Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/commerce/custsvc/returns/ModifyRefundValuesActor/resetRefundValues"

310 6 Internal REST MVC Service Call Examples

Responding to Customers

There are two actors that allow an agent to use the tasks found on the Respond Tab in the UI. These tasks enable

agents to respond to customers using e-mail.

The RespondEmailActor is used by agents to respond to e-mail from a customer. This actor is located at /atg/

svc/agent/ui/formhandlers/RespondEmailActor, and contains the following actor-chains:

Actor-Chain Description

sendEmail Allows an agent to send e-mail using the Send Email form on the

Respond Tab.

addAttachment Allows an agent to add an attachment to the e-mail.

discardEmail Enables an agent to discard e-mail.

Sending a Customer E-Mail

The sendEmail actor-chain allows an agent to send an e-mail.

Parameter Description

to This required parameter identifies the customer e-mail address.

cc Identifies any addresses to be added to the cc field.

bcc Identifies any addresses to be added to the bcc field.

subject This required parameter provides the subject of the e-mail.

htmlBody Identifies the HTML body of the e-mail.

textBody Identifies the text body of the e-mail.

Send E-Mail Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"to\" :\"customername@example.com\", \"subject\" : \"We got your request\",\"textBody\" : \"The text for the email\", \"htmlBody\" : \"The HTML body of theemail\" }" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/RespondEmailActor/sendEmail"

Adding an Attachment to an E-Mail

The addAttachment actor-chain allows an agent to add an attachment to an e-mail.

6 Internal REST MVC Service Call Examples 311

Parameter Description

windowId The window ID of the attachment.

fileAsString The file conversion string.

contentType The content type of the file to attach.

fileSize The size of the file to attach.

fileName The name of the file to attach.

tempDir The location of the temporary directory where the attachment is stored.

attachmentDisplayName The name that will be displayed for the attachment.

Add Attachment Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"windowId\" : \"1\", \"fileAsString\" : \"LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0xMDU3MDczMDI5NjAxNTY2MTEzNjkyMDY4MTQNCkNvbnRlbnQtRGlzcG9zaXRpb246IGZvcm0tZGF0YTsgbmFtZT0iX2R5bmNoYXJzZXQiDQoNClVURi04DQotLSS0tLS0tLS0tLS0tMTA1NzA3MzAyOTYwMTU2NjExMzY5MjA2ODE0LS0NCg==\", \"contentType\" : \"multipart/form-data; boundary=----------------105707302960156611369206814\", \"fileSize\" : \"40\", \"fileName\" :\"copyofinvoice\",\"tempDir\" : \"/home/order/invoice/\","attachmentDisplayName" : \"Copy of Invoice\" }" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/RespondEmailActor/addAttachment"

Discarding an E-Mail

The discardAttachment actor-chain allows an agent to discard an e-mail.

Parameters: None

Discard E-Mail Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/RespondEmailActor/discardEmail"

Sending Customer E-Mail and Closing Ticket

The SendAndCloseTicketActor allows an agent to send an e-mail and close the corresponding ticket.

It is located at /atg/svc/agent/ui/formhandlers/SendAndClosetTicketActor, and contains the

sendAndCloseTicket actor-chains.

312 6 Internal REST MVC Service Call Examples

Parameter Description

to This required parameter identifies the customer e-mail address.

cc Identifies any addresses to be added to the cc field.

bcc Identifies any addresses to be added to the bcc field.

subject This required parameter provides the subject of the e-mail.

htmlBody Identifies the HTML body of the e-mail.

textBody Identifies the text body of the e-mail.

doWarnings If set to true, will present a warning to the agent when proceeding to

the new site.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

ticketDispositionOptions.dispositionOptionIf doTicketDispositionPrompt is enabled, this provides a ticket

disposition option.

ticketDispositionOptions.reasonCodeIf doTicketDispositionPrompt is selected, this provides a ticket

disposition reason code.

ticketDispositionOptions.ticketNoteIf doTicketDispositionPrompt is selected, provides a note

associated with the ticket.

ticketDispositionOptions.publicNoteIf doTicketDispositionPrompt is selected, identifies if the ticket

note is public.

Send E-Mail and Close Ticket Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{ \"to\" :\"customer@example.com\", \"subject\" : \"We're glad you're happy! \",\"textBody\" : \"Body of the email goes here\", \"htmlBody\" : \"Body of the HTMLgoes here\" }" "http://localhost:8180/rest/model/atg/svc/agent/ui/formhandlers/SendAndCloseTicketActor/sendAndCloseTicket"

Working with the Commerce Service Center Environment

There are a number of actors that enable an agent to work with the Commerce Service Center UI and

environment.

6 Internal REST MVC Service Call Examples 313

Obtaining Global Session Information

The GlobalInfoActor contains the globalInfo actor-chain that obtains environment information including

agent profile information, environment tools and current session values. The path for this actor is /atg/

commerce/custsvc/GlobalInfoActor.

Parameters: None.

Global Information Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/environment/GlobalInfoActor/globalInfo"

This REST service call returns a server response similar to the following, providing current session values:

{ "currentSite": { "id": "storeSiteUS", "name": "CRS Home" }, "currentSalePriceList": { "id": "salePrices", "displayName": "Sale Prices" }, "currentAgent": { "id": "Call Center Agent", "lastName": "Agent", "login": "Call Center Agent", "firstName": "Call Center" }, "currentLocale": { "language": "en", "displayName": "English (United States)", "country": "US" }, "currentCustomer": { "middleName": C, "id": "830013", "lastName": "Smith", "login": null, "firstName": "John" }, "currentCatalog": { "id": "homeStoreCatalog", "status": "other", "displayName": "Home Store Catalog" }, "currentCallState": { "startTime": null, "callActive": false }, "currentOrder": {"id": "o99660003", "currentPriceList": { "id": "listPrices", "displayName": "List Prices" },

314 6 Internal REST MVC Service Call Examples

"currentTicket": {"id": "5501"}}

Listing Available Sites

The SiteGroupsActor contains the getSites actor-chain that obtains a list of grouped and ungrouped

sites. For information on site groups, refer to the Multisite Administration Guide. The path for this actor is /atg/

dynamo/droplet/multisite/SiteGroupsActor.

Parameters: None.

List Available Sites Example

curl -x 127.0.0.1:8888 -L -v -b agent_cookies.txt -H "Content-Type:application/json" "http://localhost:8280/rest/model/atg/dynamo/droplet/multisite/SiteGroupsActor/getSites"

This REST service call returns a server response similar to the following, providing a list of sites:

{ "groupedSites": [ { "id": "storeSiteUS", "name": "CRS Store" }, { "id": "homeSite", "name": "CRS Home" }, ], "ungroupedSites": []}

Selecting a Site

The ChangeSiteActor contains the selectSite actor-chain that allows an agent to select a specific site. This

actor can be configured to present ticket disposition warnings and prompts. The path for this actor is /atg/

svc/agent/environment/ChangeSiteActor.

Parameter Description

siteId The ID of the site to select.

doWarnings If set to true, will present a warning to the agent when proceeding

to the new site.

doTicketDispositionPrompt If set to true, will present ticket disposition prompts to the agent.

6 Internal REST MVC Service Call Examples 315

Parameter Description

dispositionOption If doTicketDispositionPrompt is selected, this provides a ticket

disposition option.

reasonCode If doTicketDispositionPrompt is selected, this provides a ticket

disposition reason code.

ticketNote Used to provide a note associated with the ticket.

publicNote Identifies if the ticket note is public.

Select Site Example

curl -x 127.0.0.1:8888 -L -v -b agent_cookies.txt -H "Content-Type:application/json" -d "{ \"siteId\" : \"mobileStoreSiteUS\" }""http://localhost:8280/rest/model/atg/svc/agent/environment/ChangeSiteActor/selectSite"

A server response similar to the following may occur:

{ "allWarnings":["You are changing sites. Please ensure that all work is saved."}, "activeTIcketDisposition":false, "isDiscardable":true}

Viewing Messages

The MessageToolsActor contains the messages actor-chain that allows an agent to see messages. Once a

message has been read from the message queue by the messages actor-chain, the message is removed from

the message queue. The path for this actor is /atg/web/messaging/MessageToolsActor.

Parameters: None

Display Messages Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" "http://localhost:8280/rest/model/atg/web/messaging/MessageToolsActor/messages"

The server response may be something similar to the following:

{"messages":[ { "summary":"No default site has been configured.", "params":null, "type":"warning", "requestUrl":"/rest/model/atg/userprofiling/InternalProfileActor/

316 6 Internal REST MVC Service Call Examples

login-success?atg-rest-output=json&_requestid=63", "messageDetails":[], "timestamp":{"time":1364498690397}, "priority":-5, "messageGroup":null, "datetime":{"time":1364498690397}, "identifier":null }, { "summary":"First valid active site has been chosen.", "params":null, "type":"information", "requestUrl":"/rest/model/atg/userprofiling/InternalProfileActor/ login-success?atg-rest-output=json&_requestid=63", "messageDetails":[], "timestamp":{"time":1364498690486}, "priority":-10, "messageGroup":null, "datetime":{"time":1364498690486}, "identifier":null }]}

Working with Ticket Disposition Warnings and Messages

Actions that agents perform in Commerce Service Center are linked to ticket actions. Whenever an agent

performs an action, it is possible that there will be an environment change made. Whenever an environment

changes, a warning or a ticket disposition message may occur.

By default, ticket dispositions may occur with the following REST MVC calls:

• Logging Out – The logout actor-chain

• Start New Call – The startNewCall actor-chain

• End Call – The endCall actor-chain

• Change Current Customer – The selectCustomer actor-chain

• Change Order - The changeOrder actor-chain

• Change Site – The selectSite actor-chain

When these warnings or messages occur, the data that can be returned is:

• Error – An error message is displayed

• Success – A success message is displayed

• Confirm – There are three confirmation chains that are presented:

• allWarnings – Identifies all warning messages

• isActiveTicketDisposition – Identifies if an open ticket must be processed

6 Internal REST MVC Service Call Examples 317

• isDiscardable – Indicates that the current ticket can be discarded

The following is an example of what the confirm chain returns as data:

{ "allWarnings":["The current working order has items in it and has not been saved. If you continue, the order will be lost."}, "activeTIcketDisposition":false, "isDiscardable":true}

If you create an actor that requires a disposition message or error, it must provide information for the

environmentChangeState service. The following example shows how the changeOrderActor includes the

parameters referenced by the environmentChangeState service and defines the confirm actor-chain.

Note: The three environmentChangeState modifications are identified by comments in this example:

<actor-chain id="changeOrder" transaction="TX_SUPPORTS"> <form id="changeOrder" name="/atg/commerce/custsvc/environment/ChangeOrder" var="changeOrder" handle="changeEnvironment"> <input name="inputParameters.newOrderId" value="${param.newOrderId}"/>

<!-- Add for environmentChangeState parameters --> <input name="doWarnings" value="${param.doWarnings}"/> <input name="doTicketDispositionPrompt" value="${param.doTicketDispositionPrompt}"/> <input name="environmentChangeState.ticketDispositionOptions. dispositionOption" value="${param.dispositionOption}"/> <input name="environmentChangeState.ticketDispositionOptions.reasonCode" value="${param.reasonCode}"/> <input name="environmentChangeState.ticketDispositionOptions.ticketNote" value="${param.ticketNote}"/> <input name="environmentChangeState.ticketDispositionOptions.publicNote" value="${param.publicNote}"/><!-- End changes -->

<input name="errorURL" value="${errorURL != null ? errorURL : '/model/atg/commerce/custsvc/environment/ChangeOrderActor/ changeOrder-error'}"/> <input name="successURL" value="${successURL != null ? successURL : '/model/atg/commerce/custsvc/environment/ChangeOrderActor/ changeOrder-success'}"/>

<!-- Add the confirmURL input for environmentChangeState --> <input name="confirmURL" value="${confirmURL != null ? confirmURL : '/model/atg/commerce/custsvc/environment/ChangeOrderActor/ changeOrder-confirm'}"/><!-- End changes -->

</form></actor-chain><actor-chain id="changeOrder-error" transaction="TX_SUPPORTS"> <actor id="error" name="/atg/commerce/custsvc/environment/ChangeOrderActor" chain-id="error" return-model-var="model"> <output id="model" add-map-children="true" value="${model}"/> </actor></actor-chain>

318 6 Internal REST MVC Service Call Examples

<actor-chain id="changeOrder-success" transaction="TX_SUPPORTS"></actor-chain>

<!-- Add changeOrder-confirm chain for environmentChangeState --><actor-chain id="changeOrder-confirm" transaction="TX_SUPPORTS"> <component id="fh" name="/atg/commerce/custsvc/environment/ChangeOrder" component-var="fh"> <output id="allWarnings" name="allWarnings" value="${fh.environmentChangeState.allWarnings}"/> <output id="isActiveTicketDisposition" name="activeTicketDisposition" value="${fh.environmentChangeState.processActiveTicketDisposition}" /> </component> <droplet id="shouldDiscardTicket" name="/atg/ticketing/droplet/ ShouldDiscardTicket" var="shouldDiscardTicketParamStack"> <input name="immediately" value="false" /> <input name="ticket" value="${nucleus['/atg/svc/agent/environment/ EnvironmentTools'].activeTicket}" /> <oparam name="output"> <output id="isDiscardable" name="isDiscardable" value="${shouldDiscardTicketParamStack.isDiscardable}" /> </oparam> </droplet></actor-chain><!-- End changes -->

<actor-chain id="error" transaction="TX_SUPPORTS"> <component id="fh" name="/atg/commerce/custsvc/environment/ChangeOrder" component-var="fh"> <output id="formError" name="formError" value="${fh.formError}"/> <output id="formExceptions" name="formExceptions" value="${fh.formExceptions}" filter-id="detailed"/> </component></actor-chain>

Part II. Legacy REST Web ServicesThis section provides information about and instructions for using the legacy Oracle Commerce Platform Representational

State Transfer (REST) Web Services.

The Legacy REST Web Services provide access to Nucleus components. Nucleus components are server-side JavaBeans

and servlets that perform the back-end functionality of a Web application—for example, enabling database connectivity,

logging, scheduling, and handling HTTP requests. The Oracle Commerce Platform REST Web Services expose methods that

get component data and get and set component property values. You cannot use the Oracle Commerce Platform REST Web

Services to delete components.

Note: The Oracle Commerce Platform Legacy REST Web Services are not related to the SOAP Web Services described

previously in this guide. The REST and SOAP modules do not share any functionality. The two technologies were developed

independently and are quite different in their implementations.

Important: If you are creating new REST Web Services, you should create them using the REST MVC API described in the Part

I, “Oracle Commerce Platform REST MVC Web Services” (page 67) section. The Legacy REST API is limited in its ability to be

configured and is not extensible.

7 Using Legacy REST Web Services 321

7 Using Legacy REST Web Services

This section provides general information about and instructions for using the Oracle Commerce Platform

Legacy REST Web Services interface.

HTTP Requests for Legacy REST

This section provides information about the HTTP requests that you can send to the Legacy REST Web Services

running on an Oracle Commerce Platform server.

Nucleus Components

The URL for addressing a Nucleus component includes /bean/ in its application path. The following example

shows the beginning of the URL for a Nucleus component.

http://servername:port/rest/bean/

You can use URLs to invoke methods and get or set property values of Nucleus components by including the

names of methods and properties in the application path of the component. Separate the name of the method

or property with a forward slash as if it were a separate container. For example, the following URL addresses the

running property of the atg/dynamo/Configuration component.

http://servername:port/rest/bean/atg/dynamo/Configuration/running

See information about performing operations with Nucleus component properties and methods in Working

with Legacy REST Components (page 347) and Invoking Legacy REST Component Methods (page 349).

Repositories

The URL for addressing a repository item with the Legacy REST Web Services includes /repository/ in its

application path. The following example shows the beginning of the URL for a repository item.

http://servername:port/rest/repository/

322 7 Using Legacy REST Web Services

You can address specific repository items and get or set repository item property values. Include the names

of repository items and values in the application path. Separate the names and values with a forward slash

as if it were a separate container. For example, the following URL addresses the user repository item in the

ProfileAdapterRepository repository.

http://servername:port/rest/repository/atg/userprofiling/ProfileAdapterRepository/user

The following URL addresses a specific user record in the user repository item. The value of the id property at

the end of the path indicates which user.

http://servername:port/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/210002

The following URL addresses a specific property of a user record in the user repository item.

http://servername:port/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/210002/login

See information about performing operations with repositories in Working with Repositories in Legacy

REST (page 358).

Handling POST Requests as Other Methods

In some situations you may need to submit a POST HTTP request when an operation requires a different

method. The REST Web Services server recognizes control parameters that alter the way that it handles POST

requests. See information about control parameters in Adding Control Parameters (page 61).

Note: If you are using Legacy REST Web Services, you can use the atg-rest-http-method control parameter

to process an HTTP POST request as a GET, PUT, or DELETE request. This allows you to perform operations that

require GET, PUT, or DELETE methods even if your client software cannot send HTTP messages with them. For

example, you can include message body data with an HTTP POST request but have the server process it as if it

were an HTTP GET request.

Client Software

You can use any means of transmitting HTTP requests to the Legacy REST Web Services that you wish. Any client

software that is capable of sending and receiving messages via HTTP will be adequate. Select the client software

that you use according to the requirements of your environment.

Oracle Commerce Platform Clients for the Legacy REST Web Services

Oracle Commerce Platform provides two client libraries that you can use to interact with Legacy REST Web

Services. These clients make the Legacy REST Web Services easier to use by hiding the complexity of creating

connections, assembling payloads for requests, and processing responses. See information about the clients in

Legacy Rest Client Libraries (page 385).

7 Using Legacy REST Web Services 323

Logging In

Before you can use Legacy REST Web Services you must log in to open an authorized HTTP session. When the

server receives a log in request for a valid user account, it authenticates the user and returns a session identifier

if the authentication is successful.

The procedure for logging in to the Legacy REST Web Services server is different for external and internal users.

External users are customer or other users of outward or customer-facing Web sites. Internal users are those

who have access to agent-facing servers, such as call center agents using Oracle Commerce Service Center. See

specific procedures with examples in Logging In as an External User (page 323) and Logging In as an Internal

User (page 324).

Handling Session Identifiers

When you successfully log in to the Legacy REST Web Services server, it returns a session identifier with its HTTP

response. The HTTP client that you use must present that session identifier each time it interacts with the Legacy

REST Web Services server. One method for handling the session identifier is to allow the server to set it in a

cookie file for the client.

The specific procedure you use to handle the session identifier depends on the client software you are using.

The examples in Logging In as an External User (page 323) and Logging In as an Internal User (page 324)

show how one HTTP client stores the session identifier in a cookie file.

Logging In as an External User

Invoke the /atg/userprofiling/ProfileServices.loginUser method to log in to the Legacy REST Web

Services server as an external user. Supply your username and password as functional parameters with the HTTP

POST request. Use the positional parameter name arg1 for the username and arg2 for the password.

See information about functional parameters and invoking methods in Functional Parameters for Legacy

REST (page 327) and Invoking Legacy REST Component Methods (page 349).

Success and Failure Responses for External User Log In

If your attempt to log in is successful, the Legacy REST Web Services server will return the identifier of the user

account in an HTTP response with status code 200 OK. For example, <atgResponse>120001</atgResponse>.

If your attempt to log in fails, the server will return a null value in an HTTP response with status code 200 OK. For

example, <atgResponse/>.

Note: the server returns status code 200 OK in both conditions. Make sure you examine the response value to

determine whether an attempt to log in succeeded.

Example of Logging in as an External User

The following example shows an HTTP request to open a Legacy REST Web Services session as an external user.

The server returns a session identifier in the field labeled JSESSIONID.

curl -v -c cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2></parameters>" \http://myserver:8280/rest/bean/atg/userprofiling/ProfileServices/loginUser

* About to connect() to myserver port 8280 (#0)

324 7 Using Legacy REST Web Services

* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8280 (#0)> POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8280> Accept: */*> Content-Type: application/xml> Content-Length: 71>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Added cookie JSESSIONID="7978B952714AB08BEB006A348A25ADB0" for* domain myserver, path /, expire 0< Set-Cookie: JSESSIONID=7978B952714AB08BEB006A348A25ADB0; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=* Added cookie DYN_USER_ID="120001" for domain myserver, path /, expire 1290872360< Set-Cookie: DYN_USER_ID=120001; Expires=Sat, 27-Nov-2010 15:39:20 GMT; Path=/* Added cookie DYN_USER_CONFIRM="bca3eb6c2cdeb0e4a625c7165a088e2e" for domainmyserver, path /, expire 1290872360< Set-Cookie: DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e;Expires=Sat, 27-Nov-2010 15:39:20 GMT; Path=/< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Thu, 28 Oct 2010 15:39:20 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>120001</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Specifying a Profile Realm

Include the pushRealm URL query parameter to specify a profile realm while you are logging in to the Legacy

REST Web Services interface. Include the identifier of the profile realm as the value of the pushRealm parameter.

See information about profile realms in the Multisite Administration Guide. See information about the pushRealm

parameter in the Platform Programming Guide.

For example:

http://mydomain.com/rest/bean/atg/userprofiling/ProfileServices/loginUser?pushRealm=myrealmid

Logging In as an Internal User

Invoke the Login operation of the /atg/userprofiling/InternalProfileFormHandler component

to log in to the Legacy REST Web Services server as an internal user. Supply your username and password as

functional parameters with the HTTP POST request. Use the parameter name value.login for the username

and value.password for the password.

See information about functional parameters and invoking form handler components in Functional Parameters

for Legacy REST (page 327) and Invoking Legacy REST Form Handlers (page 350).

7 Using Legacy REST Web Services 325

Include the atg-rest-return-form-handler-exceptions control parameter when you invoke this form

handler. This will cause the server to return exceptions that occur during the log in operation. If you do not

include this control parameter, you will not be able to distinguish between a successful attempt to log in and

one that fails. See Success and Failure Responses for Internal User Log In (page 325).

Success and Failure Responses for Internal User Log In

Make sure you include the atg-rest-return-form-handler-exceptions control parameter when you

invoke /atg/userprofiling/InternalProfileFormHandler/login. If you do not use this control

parameter, you will not be able to distinguish between a successful log in attempt and one that fails. See Adding

Control Parameters (page 61)..

If your attempt to log in is successful, the Legacy REST Web Services server will return a response with no

exceptions and the HTTP status code 200 OK. For example:

<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result></atgResponse>

If your attempt to log in fails, the server will return the exceptions encountered in an HTTP response with status

code 200 OK. For example:

<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions> <formExceptions> <element>The password is incorrect</element> </formExceptions> </exceptions> <result>true</result></atgResponse>

Note: the server returns status code 200 OK in both conditions. Make sure you examine the response value to

determine whether an attempt to log in succeeded.

Example of Logging in as an Internal User

The following example shows an HTTP request to open a Legacy REST Web Services session as an internal user.

The server returns a session identifier in the field labeled JSESSIONID.

curl -v -c cookies.txt -X POST \-H "Content-Type: application/json" \-d "{ value.login=MyInternalUsername , value.password=MyInternalPassword }" \http://myserver:8280/rest/bean/atg/userprofiling/InternalProfileFormHandler/login?atg-rest-return-form-handler-exceptions=true

* About to connect() to myserver port 8280 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8280 (#0)> POST /rest/bean/atg/userprofiling/InternalProfileFormHandler/login?atg-rest-return-form-handler-exceptions=true HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5

326 7 Using Legacy REST Web Services

> Host: myserver:8280> Accept: */*> Content-Type: application/json> Content-Length: 70>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Added cookie JSESSIONID="09FA8F5B4B8A4C1A1E97480A91BA7EB8" for domain myserver,path /, expire 0< Set-Cookie: JSESSIONID=09FA8F5B4B8A4C1A1E97480A91BA7EB8; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAsU2VhcmNoLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWFyY2hBZG1pbkxpY2Vuc2UvMCBQdWJsaXNoaW5nTGljZW5zZS8wIEIyQ0xpY2Vuc2UvMCAgXQ==< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Thu, 28 Oct 2010 20:57:22 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Logging Out

Users end their Legacy REST Web Services session by logging out. Once logged out, no client will be able to

perform Legacy REST Web Services operations using the session ID that was presented with the log out request.

Invoke the /atg/userprofiling/ProfileServices.logoutUser method to log out of the Legacy REST

Web Services server. Use the HTTP POST method.

The following example shows an HTTP request to log out of a Legacy REST Web Services session.

curl -v -b cookies.txt -X POST \http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/logoutUser

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/userprofiling/ProfileServices/logoutUser HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=120001; JSESSIONID=51B1124DFFC8293CF42ACA8AF2D88324;> DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=

7 Using Legacy REST Web Services 327

QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Thu, 28 Oct 2010 20:41:00 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>void</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Functional Parameters for Legacy REST

Functional parameters provide data that is required by the Legacy REST Web Services operation you are

performing. For example, if you are setting a property value, the new value is a functional parameter of the

operation.

You can include functional parameters either in the URL for the Legacy REST Web Service or in the message

body of a POST or PUT request.

The functional parameters you provide for a Legacy REST Web Services operation depend on the nature of that

operation. When invoking a method, you may supply arguments to it. When invoking a form handler, you will

supply the form field values. When setting a repository item property value, you will supply the new value. The

functional parameters for each operation are explained in the procedures for those operations. See operational

procedures in the following sections.

• Working with Legacy REST Components (page 347)

• Invoking Legacy REST Component Methods (page 349)

• Working with Repositories in Legacy REST (page 358)

Positional Parameters

Some Legacy REST Web Services operations require parameters that are not named. For example, if you invoke

the loginUser method of the /atg/userprofiling/ProfileServices component you must pass in two

positional arguments. The first is the login value for a user and the second is the password value for that user.

The Legacy REST Web Services server uses a convention to name positional parameters. It expects the first

positional parameter to be named arg1, the second to be named arg2, and any further parameters to be

named similarly.

The URL parameters in the following Legacy REST Web Services URL contain positional parameters that are

passed to the loginUser method.

http://servername:port/rest/bean/atg/userprofiling/ProfileServices/loginUser?arg1=MyUsername&arg2=MyPassword

328 7 Using Legacy REST Web Services

The Legacy REST Web Services server will call the loginUser method with the arguments in the positional

parameters arg1 and arg2 in that sequence. The method definition for loginUser is shown below. See

information about invoking methods in Invoking Legacy REST Component Methods (page 349).

public String loginUser(String pLogin, String pPassword) throws ServletException

The Legacy REST Web Services server can interpret message body parameters in XML, JSON or URL query

strings. Make sure you set the correct Content-Type value for the markup that you use.

XML Parameter Markup in Legacy REST Services

You can use XML to format parameters in the message body of an Oracle Commerce Platform REST Web Services

request.

Enclose all message body content in a parameters element as shown in the example below. Include each

parameter in a separate child element. Use the name of the parameter as its element name.

<parameters> <login>Username</login> <password>Password</password> <atg-rest-user-input>MyMessageId</atg-rest-user-input></parameters>

Make sure that you specify Content-Type: application/xml in the HTTP message.

JSON Parameter Markup in Legacy REST Services

You can use JSON to format parameters in the message body of a Legacy REST Web Services request.

Enclose the parameters in standard JSON format as shown in the example below. Include each parameter in a

separate name and value pair. Use the name of the parameter as the name for the pair. For positional parameters

that do not have names, use the arg1, arg2, arg3 convention as the names for the pairs.

{ "login": "Username", "password": "Password", "atg-rest-user-input": "MyMessageId"}

Make sure that you specify Content-Type: application/json in the HTTP message.

The Legacy REST Web Services server will only accept parameters in the message body of a POST or PUT HTTP

request. If you need to use the GET or DELETE methods, you need to include data with your request, and you

cannot include URL parameters, use the atg-rest-view and atg-rest-http-method control parameters. See

Handling POST Requests as Other Methods (page 322).

URL Query String Parameter Markup

You can use the URL query string format to include parameters in the message body of a Legacy REST Web

Services request.

7 Using Legacy REST Web Services 329

Include the parameters in standard URL query string format as shown in the example below. Include each

parameter in a separate name and value pair. Use the name of the parameter as the name for the pair. For

positional parameters that do not have names, use the arg1, arg2, arg3 convention as the names for the pairs.

See Positional Parameters (page 327).

arg1=MyUsername&arg2=MyPassword&atg-rest-user-input=MyMessageId

URL encode any special URL characters in the parameter values. Make sure that you specify Content-Type:

application/x-www-form-urlencoded in the HTTP message.

Input Values in Legacy REST Web Services

This section provides information about the way the Legacy REST Web Services server expects to receive

parameter values.

Using Primitive Values in Input

Format primitive values as shown in the following table.

Value Type Values Accepted

String A sequence of characters. For example, “MyUsername.”

Number An integer or decimal number. For example, “123” or “123.456.”

Boolean true or false

Using Multiple Values in Input

The Legacy REST Web Services server will accept map and collection input when you set the values of properties

that accept multiple values.

You can configure the way the Legacy REST Web Services server appends or replaces multiple values in a

repository item property.

When you set the value of a non-repository, Nucleus component property, the Legacy REST Web Services

server will replace all values with any new values that you set. To append a value to an existing collection, you

must supply all the existing values along with the new values. Note that unless you are setting the value of a

repository item, you must specify the Java classes used for the container and the contents.

The following example shows a Legacy REST Web Services request that appends a value to a non-repository

component property. It includes all existing values in the property along with the new value. To remove a value,

make a similar request that includes only the values that you wish to remain in the property.

curl -v -b cookies.txt -X POST \-H "Content-Type: application/json" \-d "{'atg-rest-param-class-types':{'container-class':'java.util.ArrayList','element-class':'java.lang.String'},'arg1':['Existing String in the Collection','New String for the Collection']}" \

330 7 Using Legacy REST Web Services

http://myserver:7003/rest/bean/atg/MyDog/tricks?atg-rest-json-input=true

Specifying Java Classes for Multiple Value Input

Specify the Java classes for your array, collection, and map values as shown in the following table.

Value Type Format

Array <array-element-class>:[value1,value2,...,valueN]

For example:

java.lang.String:[foo,bas,baz]

Collection <collection-container-class>:<element-class>:

[value1,value2,...,valueN]

For example:

java.util.ArrayList:java.lang.String:[foo,bas,baz]

Map <map-class>:<key-class>:<value-class>:

[key1=value1,key2=value2,key3=value3]

For example:

java.util.HashMap:java.lang.String:java.lang.String:

[foo=football,baz=basketball,bas=baseball]

If your input is in JSON format, you can use the atg-rest-param-class-types control parameter to specify

Java classes. The atg-rest-param-class-types parameter includes two components, container-class

and element-class. Include this attribute in your JSON input as shown below.

{'atg-rest-param-class-types':{'container-class':'java.util.ArrayList','element-class':'java.lang.String'},'arg1':['sit','stay','speak']}

See information about the atg-rest-param-class-types parameter in the Adding Control Parameters (page

61) section.

Legacy REST Web Services are configured to append values to repository item properties using the atg-rest-

append-multi-values control parameter. For information this parameter, refer to the Using Multiple Values in

Input (page 329) section.

Appending Values to Repository Item Properties

To append data to a repository item property that holds multiple values, set the new value as you would for a

single value property.

The following example adds two repository item reference values to a repository item property that can hold

multiple values. Any existing values in that property will remain there.

7 Using Legacy REST Web Services 331

curl -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40050,/atg/commerce/gifts/Giftlists/gift-list/gl40052</arg1></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/giftlists

Note: The Legacy REST Web Services server is configured to append values to repository item properties that

accept multiple values by default. The appendMultiValuesByDefault configuration property controls this

behavior for repository item properties. If you have reconfigured this setting, set the atg-rest-append-

multi-values control parameter to true for each Legacy REST Web Services request that should append the

new value.

Replacing Multiple Values in a Repository Item Property

To replace all the existing values in a repository item property that holds multiple values, include the atg-rest-

append-multi-values control parameter with your Legacy REST Web Services request. Set the value of the

control parameter to false.

Note: You can only use the rest-append-multi-values control parameter with repository item properties. It

does not affect the way you can update non-repository properties.

The following example replaces all the values that are currently in a repository item property that holds multiple

values. Only the repository item reference that is in the functional parameter will remain in the property.

curl -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40049</arg1></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/giftlists?atg-rest-append-multi-values=false

JSON Markup Input for Multiple Value Repository Item Properties

If you are setting multiple values in a repository item property, you can use standard JSON markup for the

collection or map value. Include the atg-rest-json-input with your Legacy REST Web Service request and

set its value to true.

You can include JSON markup for multiple values in any input format. The following example shows a Legacy

REST Web Services request that includes a JSON collection in an XML message body parameter.

curl.exe -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>[ "/atg/commerce/gifts/Giftlists/gift-list/gl40050","/atg/commerce/gifts/Giftlists/gift-list/gl40052" ]</arg1></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/giftlists?atg-rest-json-input=true

Using Object Values in Input

To set a property that takes a Java object as its value, include the atg-rest-class-type control parameter

along with the initial properties for the object in the positional parameter for the property value. The atg-

332 7 Using Legacy REST Web Services

rest-class-type control parameter specifies the Java class of the object. Use either JSON or XML to enclose

the positional parameter.

The Legacy REST Web Services server will return a Boolean value to indicate whether the object property has

been set successfully. If it is set successfully, the returned value is true.

Note: The Legacy REST Web Services interface can only create objects of classes that have a null constructor. At

least one constructor for the class must have no arguments.

The following is an object property value encoded in JSON. The class for the object is atg.MyObjectValue. The

following parameters set properties of the new object.

{"arg1": {"atg-rest-class-type" : "atg.MyObjectValue", {"atg-rest-values": { "name" : "Berthoud", "height" : "1"}}

Here is the same object property value, encoded in XML.

<parameters> <arg1> <atg-rest-class-type>atg.MyObjectValue</atg-rest-class-type> <atg-rest-values> <name>Berthoud</name> <height>1</height> </arg1></parameters>

The following example shows a POST request to set an object property value for a Nucleus component.

$ curl -v -b cookies.txt -X POST -H "Content-Type: application/json" -d"{"arg1":{"atg-rest-class-type":"atg.MyObjectValue","name":"Berthoud","height":"1"}}"http://myserver:7003/rest/bean/atg/MyDog/objectvalue* About to connect() to myserver port 7003 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 7003 (#0)> POST /rest/bean/atg/MyDog/objectvalue HTTP/1.1> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5> Host: myserver:7003> Accept: */*> Cookie: JSESSIONID=llf3PN8N0CfQ6h41Y278NfLjvCJZn6CR8ydhQRbg7GTQ7Nn5mW8p!1359398113;DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001> Content-Type: application/json> Content-Length: 69>< HTTP/1.1 200 OK< Date: Wed, 29 Feb 2012 05:52:39 GMT< Transfer-Encoding: chunked< Content-Type: application/json; charset=UTF-8< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=

7 Using Legacy REST Web Services 333

< X-Powered-By: Servlet/2.5 JSP/2.1<* Connection #0 to host myserver left intact* Closing connection #0{"atgResponse": true}

Using Nested Multiple Value Objects in Input

To set a property value that takes a Java object that holds other Java objects, use the atg-rest-class-

descriptor control parameter to specify the Java class of the nested objects. For example, if you are setting

a property value that takes a List of Sets, indicate the Java class of the Set using the atg-rest-class-

descriptor parameter. Then include the values for the nested Sets.

The name of the parameter inside the atg-rest-class-descriptor matches the name of one of the actual

values that you supply later in the input parameter.

The input structure for nested multiple value objects builds on the structure for input objects in general.

The following example uses the atg-rest-class-descriptor control parameter to specify that the

value of the myListOfSets property is a java.util.ArrayList object. That ArrayList object holds

java.util.HashSet objects. After the atg-rest-class-descriptor, the example provides the values that

are nested inside the myListOfSets property.

{arg1 : { "atg-rest-class-type":"foo.class.WithNestedMultis", "atg-rest-class-descriptor": { "myListOfSets": { "container-class": "java.util.ArrayList", "element-class": "java.util.HashSet" } }, "myListOfSets": [["red","blue"],["green","yellow"]] }}

Here is the same object property value, encoded in XML.

<arg1> <atg-rest-class-type>foo.class.WithNestedMultis</atg-rest-class-type> <atg-rest-class-descriptor> <myListOfSets> <container-class>java.util.ArrayList</container-class> <element-class>java.util.HashSet</element-class> </myListOfSets> </atg-rest-class-descriptor> <myListOfSets> <element> <element>red</element> <element>blue</element> </element> <element> <element>green</element> <element>yellow</element> </element> </myListOfSets></arg1>

334 7 Using Legacy REST Web Services

Using Three or More Nested Levels

Include additional container-class and element-class parameters for each nested level of multiple value

objects. The element-class parameter of the parent object holds the additional container-class and

element-class parameters.

For example:

"atg-rest-class-descriptor": { "myListOfSets": { "container-class": "java.util.ArrayList", "element-class": { "container-class": "java.util.HashSet", "element-class": "java.util.HashMap" } } }

Adding Date Format in Input

Use the following date format when sending dates to the Legacy REST Web Services interface.

MM/DD/YYYY HH:MM:SS Z

For example, 01/29/2015 14:45:11 PDT

Setting Properties to Null

Use the atg-rest-null parameter to set the value of a component or repository item property to null. Set the

property and include this parameter as the new value.

The following example sets the value of a component property to null.

$ curl -v -b cookies.txt -X POST \-H "Content-Type: application/json" \-d "{"arg1":"atg-rest-null"}" \http://myserver:7003/rest/bean/atg/MyDog/name* About to connect() to myserver port 7003 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 7003 (#0)> POST /rest/bean/atg/MyDog/name HTTP/1.1> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5> Host: myserver:7003> Accept: */*> Cookie: JSESSIONID=S31vPTNFpLQQ7Bj6l16wh5KgDqqv18yXxwy1khgBpvqRkW5NfQRm!1359398113; DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001> Content-Type: application/json> Content-Length: 20>< HTTP/1.1 200 OK< Date: Thu, 01 Mar 2012 01:18:50 GMT< Transfer-Encoding: chunked< Content-Type: application/json; charset=UTF-8< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=

7 Using Legacy REST Web Services 335

< X-Powered-By: Servlet/2.5 JSP/2.1<* Connection #0 to host myserver left intact* Closing connection #0{"atgResponse": true}

Returned Data in Legacy REST

The Legacy REST Web Services server will return the results of the operations you perform in an HTTP response

message body. The contents of the returned data depend on the operation you are performing.

This section explains the formats that the server will return data in. It also explains how to configure the server to

return data in the manner you choose.

Choosing Output Markup

The Legacy REST Web Services server can return output data in either JavaScript Object Notation (JSON) or

eXtensible Markup Language (XML) format. It will enclose all returned data in a JSON object with the name

atgResponse or an atgResponse XML element.

The following example shows JSON output markup.

{"atgResponse": "280001"}

The following example shows XML output markup.

<atgResponse>280001</atgResponse>

Default Output Markup

Configure your Legacy REST Web Server to return output data in the format you choose. The default output

format of the server is controlled by its /atg/rest/Configuration/

defaultOutputCustomizer property.

• For JSON output, set the property to /atg/rest/output/JSONOutputCustomizer.

• For XML output, set the property to /atg/rest/output/XMLOutputCustomizer.

The server will return data in its default output format if you do not specify the output format for an individual

request. See Specifying Output Markup for One Request (page 335).

Specifying Output Markup for One Request

You can choose either JSON or XML for the returned data of a single Legacy REST Web Services request. The

output format you specify for an individual request will override the default output markup setting.

To specify the output format for an individual Legacy REST Web Services request, include the atg-rest-output

control parameter with that request. Set the value of atg-rest-output to either json or xml. See Adding

Control Parameters (page 61).

336 7 Using Legacy REST Web Services

The following example shows a Legacy REST Web Services request that includes the atg-rest-output control

parameter. The control parameter specifies that data should be returned using XML markup.

curl -v -b cookies.txt -X GET \http://servername:port/rest/bean/atg/dynamo/Configuration?atg-rest-output=xml

JSON Output

The following example shows JSON output. Notice how string values are surrounded by quotes, numerical

values have no quotes, multivalve elements are surrounded by brackets, and references to repository items are

URLs to the item referenced. Note that multivalve elements will be URLs also, but in this example, the abcArray

has been expanded.

{ "myClass": "class atg.rest.processor.MockObject", "size": 10, "abcArray": { "type": "int", "elements": [ 0, 1, 2, 3 ] }, "product": "http://localhost/rest/repository/atg/commerce/catalog/ProductCatalog/product/prod12345"}

XML Output

The following example shows XML output.

<atgResponse> <organizationPathCache> <atgRestComponentPath>/atg/userprofiling/OrganizationPathCache </atgRestComponentPath> </organizationPathCache> <rootOrganizationPrimaryKey>root</rootOrganizationPrimaryKey>

[Additional property values omitted to save space]

<roles> <element>- RepositoryItemGroupRole:--&gt; name: Young--&gt; primary key: Young__grouprole</element> <element>- RepositoryItemGroupRole:--&gt; name: WomenOnly--&gt; primary key: WomenOnly__grouprole

7 Using Legacy REST Web Services 337

</element> <element>- RepositoryItemGroupRole:--&gt; name: Fashionista--&gt; primary key: Fashionista__grouprole</element> <element>- RepositoryItemGroupRole:--&gt; name: MenOnly--&gt; primary key: MenOnly__grouprole</element> <element>- RepositoryItemGroupRole:--&gt; name: ThirtySomethings--&gt; primary key: ThirtySomethings__grouprole</element> </roles>

[Additional property values omitted to save space]

</atgResponse>

Identifying a Response

You can include an identifying string with a Legacy REST Web Services request and the server will include that

string in the response it returns. One use of this function is to identify the response to an asynchronous Legacy

REST Web Service request.

To specify the identifying string for a Legacy REST Web Services response, include the atg-rest-user-input

control parameter in your HTTP request. Set the value of the control parameter to the identifying string. See

Adding Control Parameters (page 61).

The following example shows a Legacy REST Web Services request that includes the atg-rest-user-input

control parameter.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-user-input=MyMessageId001

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-user-input=MyMessageId001 HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: JSESSIONID=AD84270CB05CC0960580D1B875595822>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: application/json;charset=UTF-8

338 7 Using Legacy REST Web Services

< Transfer-Encoding: chunked< Date: Fri, 22 Oct 2010 16:36:07 GMT<{ "atg-rest-response": {"httpPort": 8080}, "atg-rest-user-input": "MyMessageId001"}* Connection #0 to host myserver left intact* Closing connection #0

Multiple Values in Output

This section provides information about the format of collection and map values in response messages from the

Legacy REST Web Services server.

Expanding Multiple Values and Complex Objects

The Legacy REST Web Services server returns multiple-values and complex objects as REST paths by default.

Include the atg-rest-show-rest-paths control parameter to expand these values in the response you

receive. Set the value of the control parameter to true.

If you set atg-rest-show-rest-paths to false, the REST response will include expanded data for nested

properties down to the level specified by the atg-rest-depth control parameter. See Return Depth (page

343).

You can configure the default setting for atg-rest-show-rest-paths.

The example below shows a REST path in the creditCards property. The example that follows it shows the

effect of the atg-rest-show-rest-paths control parameter.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="A2C79A00F7194A1F113604FD1C4BE7DD" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=A2C79A00F7194A1F113604FD1C4BE7DD; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 05 Nov 2010 21:50:44 GMT

7 Using Legacy REST Web Services 339

<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>

[Additional property values omitted to save space]

<creditCards>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/130001/creditCards</creditCards>

[Additional property values omitted to save space]

</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

The example below shows a collection value that has been expanded. The Legacy REST Web Services request

sets the atg-rest-show-rest-paths control parameter to false.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/?atg-rest-show-rest-paths=false

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/?atg-rest-show-rest-paths=false HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="9D730DE9D4A7C250994F20363ACC3FA6" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=9D730DE9D4A7C250994F20363ACC3FA6; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 05 Nov 2010 22:04:32 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>

[Additional property values omitted to save space]

<creditCards> <element> <key>MyOtherCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository </atgRestComponentPath>

340 7 Using Legacy REST Web Services

<atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10003</atgRestRepositoryId> </value> </element> <element> <key>MyCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository </atgRestComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10001</atgRestRepositoryId> </value> </element> </creditCards>

[Additional property values omitted to save space]

</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Collection Values in Output

The Legacy REST Web Services server will return each element in a property value of class

java.utils.Collection as shown in the examples below.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/userprofiling/ProfileUserDirectory/roles

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/bean/atg/userprofiling/ProfileUserDirectory/roles HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="6F710DD421CDBB1C0A092133210E7A0E" for* domain myserver, path /, expire 0< Set-Cookie: JSESSIONID=6F710DD421CDBB1C0A092133210E7A0E; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Wed, 03 Nov 2010 15:05:19 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <roles> <element>- RepositoryItemGroupRole:

7 Using Legacy REST Web Services 341

--&gt; name: Young--&gt; primary key: Young__grouprole</element> <element>- RepositoryItemGroupRole:--&gt; name: WomenOnly--&gt; primary key: WomenOnly__grouprole</element> <element>- RepositoryItemGroupRole:--&gt; name: Fashionista--&gt; primary key: Fashionista__grouprole</element> <element>- RepositoryItemGroupRole:--&gt; name: MenOnly--&gt; primary key: MenOnly__grouprole</element> <element>- RepositoryItemGroupRole:--&gt; name: ThirtySomethings--&gt; primary key: ThirtySomethings__grouprole</element> </roles></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

The following example shows the same property value in JSON format.

{"roles": [ "\n- RepositoryItemGroupRole:\n--> name: Young\n--> primary key: Young__grouprole\n", "\n- RepositoryItemGroupRole:\n--> name: WomenOnly\n--> primary key: WomenOnly__grouprole\n", "\n- RepositoryItemGroupRole:\n--> name: Fashionista\n--> primary key: Fashionista__grouprole\n", "\n- RepositoryItemGroupRole:\n--> name: MenOnly\n--> primary key: MenOnly__grouprole\n", "\n- RepositoryItemGroupRole:\n--> name: ThirtySomethings\n--> primary key: ThirtySomethings__grouprole\n"]}

Map Values in Output

The Legacy REST Web Services server will return each element in a property value of class java.utils.Map as

shown in the examples below.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/creditCards

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/creditCards HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK

342 7 Using Legacy REST Web Services

< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="F60503E5A6051C18D119B6CE470F9591" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=F60503E5A6051C18D119B6CE470F9591; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Wed, 03 Nov 2010 16:12:57 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <creditCards> <element> <key>MyOtherCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/credit-card/usercc10003</value> </element> <element> <key>MyCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/credit-card/usercc10001</value> </element> </creditCards></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

The following example shows the same property value in JSON format.

{"creditCards": { "MyCard": "http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/credit-card/usercc10001","MyOtherCard": "http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/credit-card/usercc10003" }}

Array Values in Output

The Legacy REST Web Services server will return each element in a property value that is an array as shown in

the examples below.

curl -v -b cookies.txt -X GET http://12.34.567.890:7003/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/190000/previousPasswords* About to connect() to 12.34.567.890 port 7003 (#0)* Trying 12.34.567.890... connected* Connected to 12.34.567.890 (12.34.567.890) port 7003 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/190000/previousPasswords HTTP/1.1> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5> Host: 12.34.567.890:7003> Accept: */*> Cookie: DYN_USER_CONFIRM=4587a098fc47b063d7e60c9097fa3c99; DYN_USER_ID=140001;JSESSIONID=PGpxTW0BWgSfQT2sXspwJf3H3JJKdTGHgJ1yMZ1QV8V1GRQJ9MVN!-249339435>

7 Using Legacy REST Web Services 343

< HTTP/1.1 200 OK< Date: Thu, 13 Oct 2011 16:18:22 GMT< Transfer-Encoding: chunked< Content-Type: application/xml; charset=UTF-8< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=* Replaced cookie JSESSIONID="V9TCTXPTkCnXrgJJKb2bhbzHwpvn2yzlDJb4JTXhLlkyw22J7xm7!-249339435" for domain12.34.567.890, path /, expire 0< Set-Cookie: JSESSIONID=V9TCTXPTkCnXrgJJKb2bhbzHwpvn2yzlDJb4JTXhLlkyw22J7xm7!-249339435; path=/; HttpOnly< X-Powered-By: Servlet/2.5 JSP/2.1<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <previousPasswords>

<element>17d0b74864b89840e07f08f46dd72f90fed59b62d476639c25667a3b3f74bdf5 </element>

<element>914eb28cb2996739bdd33ed74deed1005ff1fd40489583d22bd35d5a8344fa6c </element> </previousPasswords></atgResponse>* Connection #0 to host 12.34.567.890 left intact* Closing connection #0

The following example shows the same property value in JSON format.

{"previousPasswords": [ "17d0b74864b89840e07f08f46dd72f90fed59b62d476639c25667a3b3f74bdf5", "914eb28cb2996739bdd33ed74deed1005ff1fd40489583d22bd35d5a8344fa6c"]}

Return Depth

You can control the number of nested levels of property information that the Legacy REST Web Services server

will return when you request property values. Use the atg-rest-depth control parameter to specify the

number of levels that will be included in returned data.

The number of nested levels you can expand in returned data is limited by the maxDepthAllowed configuration

for the Legacy REST Web Services server.

The default number of levels is zero which returns only the immediate properties of the Nucleus component you

specify in your request. If one of those properties includes multiple values or is a complex object, the returned

data will include only the REST path of the property value. For example:

<creditCards>http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/creditCards</creditCards>

If you set the return depth to one, the returned data will expand properties that contain multiple values and

complex objects. The individual values within them will be included in the returned data. For example:

344 7 Using Legacy REST Web Services

<creditCards> <element> <key>MyOtherCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository </atgRestComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10003</atgRestRepositoryId> </value> </element> <element> <key>MyCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository </atgRestComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10001</atgRestRepositoryId> </value> </element></creditCards>

Date Format in Returned Data

You can configure the format for dates that are returned by the Legacy REST Web Services interface. It will return

dates in one of the following formats:

• A string representation of a Java Date object (default)

• mm/dd/yyyy hh:mm:ss z

For example: 01/29/2011 11:11:11 GMT

To control which date format will be returned, set the enableFormatDateOutput property of the /atg/rest/

output/JSONOutputCustomizer or /atg/rest/output/XMLOutputCustomizer components.

• Set enableFormatDateOutput to true to receive the date and time in MM/dd/yyyy HH:mm:ss z format.

• Set enableFormatDateOutput to false to receive the string representation of the Date object.

Note: The return depth for a REST request may cause a date property to be expanded. If a date property is

expanded, it will not be in either of the formats described in this section but will be a set of properties that make

up the date. See Return Depth (page 343). If you do not want to expand date properties, you can suppress

property expansion for them. See Suppressing Property Expansion in Legacy REST (page 372).

Time Zone Configuration

If you set the enableFormatDate property of the JSONOutputCustomizer or XMLOutputCustomizer

to true, the Legacy REST Web Services interface returns date values using the time zone specified by the

timeZoneId property. The default value for this property is Coordinated Universal Time (UTC).

Set the timeZoneId property of JSONOutputCustomizer or XMLOutputCustomizer to the time zone

identifier that you choose. Specify the time zone using a string recognized by the java.util.TimeZone class.

If you choose to return the string representation of Java Date objects, the Legacy REST interface will return date

values using the time zone of the server.

7 Using Legacy REST Web Services 345

Errors and Exceptions in Legacy REST

If an error or exception occurs when you use the Legacy REST Web Services, the server will indicate the nature of

the problem in the HTTP response status code. See HTTP Status Codes (page 57).

Problems Performing Operations

If the Legacy REST Web Services server can process the input in your request but it encounters problems

performing an operation it will return HTTP status code 400 Bad Request.

The following example shows an exception that has been returned by the Legacy REST Web Services

server. HTTP status code 400 Bad Request indicates that the server cannot perform the requested

action because of a problem with the input provided. The server includes the name of the exception

(atg.beans.PropertyNotFoundException) in the message body of the response.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/dynamo/Configuration/fakeProperty

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/bean/atg/dynamo/Configuration/fakeProperty HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: JSESSIONID=67B1EAF58CC556CE7C628CDE6F395FB4>< HTTP/1.1 400 Bad Request< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: text/html;charset=utf-8< Content-Length: 1585< Date: Fri, 22 Oct 2010 19:48:53 GMT< Connection: close<<html><head><title>JBoss Web/2.1.3 Error report</title><style><!--H1{font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY{font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B{font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;}P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A {color: black;}A.name {color : black;}HR {color : #525D76;}--></style> </head><body><h1>HTTP Status 400 atg.beans.PropertyNotFoundException:Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration</h1><HR size="1" noshade="noshade"><p><b>type</b> Statusreport</p><p><b>message</b> <u>atg.beans.PropertyNotFoundException: Can't findproperty named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can'tfind property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration</u></p><p><b>description</b> <u>The request sent by the client was syntacticallyincorrect (atg.beans.PropertyNotFoundException: Can't find property named:

346 7 Using Legacy REST Web Services

fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find propertynamed: fakeProperty in class: atg.service.dynamo.DAFConfiguration).</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3></body></html>* Closing connection #0

Problems Processing a Request

If the Legacy REST Web Services server cannot process the input in your request it will return HTTP status code

500 Internal Server Error.

The following example shows an exception that has been returned by the Legacy REST Web Services

server. HTTP status code 500 Internal Server Error indicates that the server cannot process the

request because of a problem interpreting the input. The server includes the name of the exception

(org.dom4j.DocumentException) in the message body of the response.

curl -v -c cookies.txt -X POST \-H "Content-Type: application/xml" -d "This is not XML." \http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Content-Type: application/xml> Content-Length: 16>< HTTP/1.1 500 Internal Server Error< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Added cookie JSESSIONID="24C3CC9056EA3A1B62DD2002DEDFAA7F" for domain myserver,path /, expire 0< Set-Cookie: JSESSIONID=24C3CC9056EA3A1B62DD2002DEDFAA7F; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: text/html;charset=utf-8< Content-Length: 1776< Date: Wed, 27 Oct 2010 18:15:29 GMT< Connection: close<<html><head><title>JBoss Web/2.1.3 Error report</title><style><!--H1{font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY{font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B{font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P{font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A {color: black;}A.name {color : black;}HR {color : #525D76;}--></style> </head><body><h1>HTTP Status 500 org.dom4j.DocumentException: Error online 1 of document : Content is not allowed in prolog. Nested exception:Content is not allowed in prolog. Error on line 1 of document : Content is notallowed in prolog. Nested exception: Content is not allowed in prolog.</h1><HR size="1" noshade="noshade"><p><b>type</b> Status report</p><p><b>message</b>

7 Using Legacy REST Web Services 347

<u>org.dom4j.DocumentException: Error on line 1 of document : Content is notallowed in prolog. Nested exception: Content is not allowed in prolog. Error online 1 of document : Content is not allowed in prolog. Nested exception: Contentis not allowed in prolog.</u></p><p><b>description</b> <u>The server encounteredan internal error (org.dom4j.DocumentException: Error on line 1 of document :Content is not allowed in prolog. Nested exception: Content is not allowed inprolog. Error on line 1 of document : Content is not allowed in prolog. Nestedexception: Content is not allowed in prolog.) that prevented it from fulfillingthis request.</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3></body></html>* Closing connection #0

Working with Legacy REST Components

This section provides instructions for the Legacy REST Web Services operations involving Nucleus component

properties.

Getting Legacy REST Component Properties

To get the value of a Nucleus component property, send a Legacy REST Web Services request as described in the

following table.

Request Component Value

HTTP Method GET

Functional Parameters None

URL Include the component pathname in the application path after /rest/

bean/. Include the name of the property at the end of the path. See Nucleus

Components (page 321).

To get the values of all properties of a component, do not include a property

name at the end of the path.

The following example shows a Legacy REST Web Services request that returns the value of the atg/dynamo/

Configuration.httpPort property.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/dynamo/Configuration/httpPort

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/bean/atg/dynamo/Configuration/httpPort HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*

348 7 Using Legacy REST Web Services

> Cookie: JSESSIONID=8DC60C0801D934F472BD9BE8A15A54F9>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 25 Oct 2010 21:29:05 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <httpPort>8080</httpPort></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

The following example shows a Legacy REST Web Services request that returns all the properties of a Nucleus

component.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/dynamo/Configuration

Setting Legacy REST Component Properties

To set the value of a Nucleus component property, send a Legacy REST Web Services request as described in the

following table.

Request Component Value

HTTP Method POST or PUT

Functional Parameters Include the new value for the property.

Use the positional parameter name arg1 for the value. See Positional

Parameters (page 327).

URL Include the component pathname in the application path after /rest/

bean/. Include the name of the property at the end of the path. See Nucleus

Components (page 321).

The following example shows a Legacy REST Web Services request that sets the value of the atg/

userprofiling/passwordchecker/PasswordRuleChecker.enabled property.

curl -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>false</arg1></parameters>" \

7 Using Legacy REST Web Services 349

http://myserver:8080/rest/bean/atg/userprofiling/passwordchecker/PasswordRuleChecker/enabled

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/userprofiling/passwordchecker/PasswordRuleChecker/enabled HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: JSESSIONID=7205768051AC55AAFD5020D8931C71A7> Content-Type: application/xml> Content-Length: 43>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Tue, 26 Oct 2010 14:58:28 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>true</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Invoking Legacy REST Component Methods

To invoke a Nucleus component method, send a Legacy REST Web Services request as described in the following

table.

Request Component Value

HTTP Method POST

Functional Parameters Include any arguments to the method as positional parameters. The name of

the parameter for the first argument is arg1. The name of the parameter for

the second argument is arg2. Continue this naming pattern for any further

arguments. See Positional Parameters (page 327).

URL Include the component pathname in the application path after /rest/

bean/. Include the name of the method at the end of the path. See Nucleus

Components (page 321).

The following example shows a Legacy REST Web Services request that invokes the /atg/commerce/order/

OrderManager.getOrderCountForProfile method. The method takes a user identifier as its argument and

it returns an integer value.

350 7 Using Legacy REST Web Services

curl -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>130001</arg1></parameters>" \http://myserver:8080/rest/bean/atg/commerce/order/OrderManager/getOrderCountForProfile

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/commerce/order/OrderManager/getOrderCountForProfile HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=120001; JSESSIONID=7C4C04BFDA404FA7D9443A820F32BE0D;DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e> Content-Type: application/xml> Content-Length: 44>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Wed, 27 Oct 2010 17:17:33 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>2</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Invoking Legacy REST Form Handlers

To invoke a Nucleus form handler, send a Legacy REST Web Services request as described in the following table.

Request Component Value

HTTP Method POST

Functional Parameters Submit the required property values of the form as functional parameters. Name

each parameter with the property name it corresponds to. See Submitting

Legacy REST Form Values (page 351).

URL Include the component pathname in the application path after /rest/bean/.

Include the name of the form handler operation at the end of the path. See

Nucleus Components (page 321).

7 Using Legacy REST Web Services 351

The following example shows a Legacy REST Web Services request that invokes the create operation of /atg/

store/profile/RegistrationFormHandler. The HTTP request includes functional parameters to supply

the value property of the form handler. The data type of the value property is java.util.Dictionary;

parameter names such as value.password correspond to the password key in the dictionary value.

curl -v -b cookies.txt -X POST \-H "Content-Type: application/json" \-d "{ "value.email":"sheroux@example.com", "value.password":"mypassword","value.confirmPassword":"mypassword", "value.firstName":"Severe","value.lastName":"Heroux" }" \http://myserver:8080/rest/bean/atg/store/profile/RegistrationFormHandler/create

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/store/profile/RegistrationFormHandler/create HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=1DEDBDEE3BF322FA71AFE89438DCCF9E;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b> Content-Type: application/json> Content-Length: 147>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=* Replaced cookie DYN_USER_ID="140003" for domain myserver, path /,expire 1291317542< Set-Cookie: DYN_USER_ID=140003; Expires=Thu, 02-Dec-2010 19:19:02 GMT; Path=/* Replaced cookie DYN_USER_CONFIRM="1231cf3e7573bf936dbd29dbbbfe150b" fordomain myserver, path /, expire 1291317542< Set-Cookie: DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b; Expires=Thu,02-Dec-2010 19:19:02 GMT; Path=/< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Tue, 02 Nov 2010 19:19:02 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>true</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Submitting Legacy REST Form Values

When you invoke a form handler, you must present it with a set of values as functional parameters. These values

are the data that would be submitted in form fields if the form handler were being invoked from a user interface.

Different types of form handlers require different parameters depending on the function they perform. See

more information about form handlers in the Page Developer's Guide.

For example, the /atg/store/profile/RegistrationFormHandler form handler requires a

java.util.Dictionary property named value that holds a set of dictionary fields. The fields in the dictionary

352 7 Using Legacy REST Web Services

property hold the values that would be entered in user interface fields on a registration form. To invoke the /

atg/store/profile/RegistrationFormHandler form handler, you must include a functional parameter for

value.email, value.password, value.confirmPassword, value.firstName, and value.lastName.

The following JSON data contains the functional parameters required by the /atg/store/profile/

RegistrationFormHandler form handler.

{ "value.email":"sheroux@example.com", "value.password":"mypassword","value.confirmPassword":"mypassword", "value.firstName":"Severe","value.lastName":"Heroux" }

Returning Legacy REST Form Handler Exceptions

Include the atg-rest-return-form-handler-exceptions control parameter with a Legacy REST Web

Services request to return form handler exceptions in the HTTP response from the server. Set the value of the

control parameter to true.

The following example shows the response to a Legacy REST Web Services request to invoke /atg/

userprofiling/InternalProfileFormHandler/login. The response includes an exceptions element

that contains information about the exception that occurred.

<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions> <formExceptions> <element>Missing value for the login property</element> </formExceptions> </exceptions> <result>true</result></atgResponse>

The following example shows the response to a successful Legacy REST Web Services request to invoke /atg/

userprofiling/InternalProfileFormHandler/login. The response includes an empty exceptions

element because no exceptions occurred.

<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result></atgResponse>

Note: if you choose to include both exceptions and form handler properties in a Legacy REST Web

Services request, the class element in the atgResponse will contain the following value: class

atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Legacy

REST Form Handler Properties (page 352).

Returning Legacy REST Form Handler Properties

Include the atg-rest-return-form-handler-properties control parameter with a Legacy REST Web

Services request to return the property values of the form handler component. The Legacy REST Web Services

7 Using Legacy REST Web Services 353

server will include the property values in a component element in the HTTP response. Set the value of the

control parameter to true.

The following example shows the response to a Legacy REST Web Services request to invoke /atg/store/

profile/RegistrationFormHandler/create. The response includes a component element that contains

the property values of the RegistrationFormHandler component.

<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerProperties</class> <component> <absoluteName>/atg/dynamo/servlet/pipeline/RequestScopeManager/ RequestScope-409/atg/store/profile/RegistrationFormHandler</absoluteName> <addCommerceItemInfos/> <addressIdValueMapKey>addressId</addressIdValueMapKey>

[Additional property values omitted to save space]

<valueMap>http://myserver:8080/rest/bean/atg/dynamo/servlet/pipeline/ RequestScopeManager/RequestScope-409/atg/store/profile/ RegistrationFormHandler/valueMap</valueMap> <verifyPasswordSuccessURL/> </component> <result>true</result></atgResponse>

Note: if you choose to include both exceptions and form handler properties in a Legacy REST Web

Services request, the class element in the atgResponse will contain the following value: class

atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Legacy

REST Form Handler Exceptions (page 352).

Legacy REST Form Value Priority

Specify the order in which form values are processed using the atg-rest-form-tag-priorities control

parameter. Set the value of the control parameter to a JSON object that assigns an integer value to any of the

form values that you wish to prioritize. Higher priority numbers are processed first. Values that you do not

prioritize are assigned the priority zero.

The following example specifies that the value.password field should be processed before any other field.

curl -v -b cookies.txt -X POST \-H "Content-Type: application/json" \-d "{ "value.email": "sheroux@example.com", "value.password": "mypassword","value.confirmPassword": "mypassword", "value.firstName": "Severe","value.lastName": "Heroux", "atg-rest-form-tag-priorities":{ "value.password": 10 } }" \http://myserver:8080/rest/bean/atg/store/profile/RegistrationFormHandler/create

354 7 Using Legacy REST Web Services

Invoking Java Server Pages (JSPs) with Legacy REST

This section provides instructions for using the Legacy REST Web Services to invoke Java Server Pages (JSPs) in

your Web applications.

You can create JSPs that access the functionality of a Web application that would otherwise be difficult to use via

Legacy REST Web Services. JSPs may combine several functions and return a purpose-built set of information to

Legacy REST Web Services clients.

Note: The Legacy REST Web Services interface does not secure access to JSPs. If your JSP provides access to

sensitive resources, make sure to include security measures such as an access control servlet in your Web

application.

The Legacy REST Web Services use the URL recoding feature of the Oracle Commerce Platform. This feature

links URL application paths (for example, http://domain/an/application/path/) to specific JSPs in a

Web application. It can identify input parameters in the URL and pass them to the JSP. See comprehensive

information about URL recoding in the Platform Programming Guide.

See instructions for configuring JSPs to be accessed by Legacy REST Web Services clients in Legacy REST Web

Services JSP Configuration Procedure (page 355).

To invoke a JSP, send a Legacy REST Web Services request as described in the following table.

Request Component Value

HTTP Method GET or POST

Functional Parameters Do not submit functional parameters when accessing JSPs via the Legacy REST

Web Services. Pass parameters in the URL that corresponds to the JSP.

The format of the parameters that you pass in the URL is configured by the URL

recoding feature of the Oracle Commerce Platform. The developers who design

the JSP and the URL recoding template control the parameter format. See URL

Templates for Legacy REST Web Services JSPs (page 355).

URL Include the component pathname that corresponds to the JSP in the application

path after /rest/service/. Include the parameters at the end of the path in the

format expected by the template.

The URL that corresponds to a JSP is configured by the URL recoding feature of

the Oracle Commerce Platform. The developers who design the JSP and the URL

recoding template control the URL and the parameter format. See URL Templates

for Legacy REST Web Services JSPs (page 355).

The following example shows a Legacy REST Web Services request that invokes a JSP. The application path and

parameters in the URL are the controlled by the example configurations shown in URL Templates for Legacy

REST Web Services JSPs (page 355). The code of the JSP itself is shown in Example Legacy REST Web Services

JSP (page 357).

$ curl -v -b cookies.txt -X GET http://myserver:7003/rest/service/atg/AnyComponent/xprod2083,foo

7 Using Legacy REST Web Services 355

* About to connect() to myserver port 7003 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 7003 (#0)> GET /rest/service/atg/AnyComponent/xprod2083,foo HTTP/1.1> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5> Host: myserver:7003> Accept: */*> Cookie: JSESSIONID=tGD0P6WBTGp62dd5QczJjM0JhpMSvzQvqMbC9jvMNhJ8fS3w33vD!-531422523; DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001>< HTTP/1.1 200 OK< Date: Tue, 14 Feb 2012 18:17:34 GMT< Content-Length: 127< Content-Type: application/json< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=< X-Powered-By: Servlet/2.5 JSP/2.1<

{"displayName":"Wine Glass Set","someString":"foo"}

* Connection #0 to host myserver left intact* Closing connection #0

Legacy REST Web Services JSP Configuration Procedure

To configure the Oracle Commerce Platform Legacy REST Web Services to make JSPs accessible by REST clients:

1. Add a JSP that generates the output required by the Legacy REST Web Services clients that will request it. See

information about developing JSPs for Oracle Commerce Platform applications in the Page Developer's Guide.

Package the JSP in your Web application so that it cannot be accessed by outside visitors. For example, place

it under the WEB-INF directory of the Web application.

See Example Legacy REST Web Services JSP (page 357).

2. Configure a URL template component to link a Legacy REST Web Services URL to the JSP. See URL Templates

for Legacy REST Web Services JSPs (page 355).

3. Add the URL template component to the templates property of the /atg/rest/processor/

ServiceProcessor component. See Configuring the Legacy REST Service Processor Component (page

356).

URL Templates for Legacy REST Web Services JSPs

Use URL templates to link Legacy REST Web Services URLs to JSPs. URL templates use regular expressions to

recognize input parameters and pass them to a JSP.

URL templates are Nucleus components that are used by the URL recoding feature of the Oracle Commerce

Platform. See comprehensive information about that feature in the Platform Programming Guide.

To create a URL template component, add a URL template properties file in the configuration path for the

Legacy REST Web Services. For example, you could configure a URL template in the file shown below.

356 7 Using Legacy REST Web Services

<ATG11dir>/home/servers/servername/localconfig/atg/rest/processor/templates/MyTemplate.properties

An example URL template component properties file is shown below.

• The urlTemplateFormat property defines the application path of the URL that Legacy REST Web Services

clients will access. It includes a comma separated list of parameters that the client must supply.

The URL format must begin with /rest/service. After that, it must contain the Nucleus path of an existing

component in your application. It does not matter which component you choose.

• The indirectRegex property matches parameters that are supplied in the URL application path. The URL

recoding feature will pass these parameters to the JSP.

• The regexElementList property provides information about each parameter. The two parameters shown in

this example are a repository item identifier and a simple string.

• The forwardUrlTemplateFormat property configures the JSP file that the Legacy REST Web Services

interface will invoke. The application path includes the context root of the Web application (mymodule in the

example). It also includes each parameter that was identified in the URL template as URL parameters that will

be passed to the JSP.

$class=atg.repository.seo.IndirectUrlTemplate

# Url template formaturlTemplateFormat=/rest/service/atg/AnyComponent/{item.id},{mystring}

# Regex that matches above formatindirectRegex=.*/rest/service/atg/AnyComponent/([^/].*?),([^/].*?)$

# Regex elementsregexElementList=item | id | /atg/AnyComponent\:product, mystring | string

# Forward Url templateforwardUrlTemplateFormat=/mymodule/WEB-INF/rest/myRestJsp.jsp?productId\={item.id}&myString\={mystring}

# Web App registrywebAppRegistry=/atg/registry/WebApplicationRegistry

Note: See comprehensive information about configuring the URL recoding feature of the Oracle Commerce

Platform in the Platform Programming Guide.

Configuring the Legacy REST Service Processor Component

Add each URL template component for your Legacy REST Web Services JSPs to the templates property of the

/atg/rest/processor/ServiceProcessor component. For example, you could configure the templates

property in the file shown below.

<ATG11dir>/home/servers/servername/localconfig/atg/rest/processor/ServiceProcessor.properties

7 Using Legacy REST Web Services 357

The example ServiceProcessor.properties file shown below adds a URL template component to the

templates property.

templates+=/atg/rest/processor/templates/MyTemplate

Example Legacy REST Web Services JSP

This section provides an example of a JSP that returns content to a Legacy REST Web Services client. The JSP

invokes a servlet bean to return data that it will incorporate into the output it sends to the REST client. In this

example, the JSP uses the /atg/commerce/catalog/ProductLookup component to return repository data to

the REST client.

See comprehensive information about developing JSPs for the Oracle Commerce Platform application in the

Page Developer's Guide.

<%-Import the dsp tag library to access Oracle ATG Web Commerce functionality. Import tag libraries for the output format you will send to REST clients. --%>

<%@ taglib prefix="dsp" uri="http://www.atg.com/taglibs/daf/dspjspTaglib1_1" %><%@ taglib prefix="json" uri="http://www.atg.com/taglibs/json" %><%@page contentType="application/json"%>

<dsp:page>

<%-Import a servlet bean component you will use with the dsp:droplet element --%>

<dsp:importbean bean="/atg/commerce/catalog/ProductLookup"/> <dsp:droplet name="ProductLookup">

<%-These two parameters are passed to the JSP by the URL recoding template. --%>

<dsp:param name="id" param="productId"/> <dsp:param name="aString" param="myString"/>

<%-Write the output for REST clients using the values returned by the servlet bean. --%>

<dsp:oparam name="output"> <json:object name="product"> <json:property name="displayName"> <dsp:valueof param="element.displayName"/> </json:property> <json:property name="someString"> <dsp:valueof param="aString"/> </json:property> </json:object> </dsp:oparam> </dsp:droplet></dsp:page>

358 7 Using Legacy REST Web Services

Working with Repositories in Legacy REST

This section provides instructions for Legacy REST Web Services operations involving repositories.

A repository item is a JavaBean component that implements atg.repository.RepositoryItem or one of its

sub-interfaces, and corresponds to the smallest uniquely identifiable entity in the underlying data store. Each

repository item is composed of named properties that store the item’s data—for example, id, firstName, and

lastName.

Listing Repository Items in Legacy REST

To list the items of a type in a repository, send a Legacy REST Web Services request as described in the following

table.

Request Component Value

HTTP Method GET

Functional Parameters None

URL Include the component pathname of the repository in the application path after

/rest/repository/. Include the name of the item type at the end of the path.

The following example shows a Legacy REST Web Services request that lists the repository items of the user

item type in the atg/userprofiling/ProfileAdapterRepository repository.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4;DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 29 Oct 2010 16:27:49 GMT<<?xml version="1.0" encoding="UTF-8"?>

7 Using Legacy REST Web Services 359

<atgResponse> <user> <element>http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/se-570040</element> <element>http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/120001</element> <element>http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/140001</element> </user></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Retrieving a Repository Item in Legacy REST

To list the properties of a repository item, send a Legacy REST Web Services request as described in the following

table.

Request Component Value

HTTP Method GET

Functional Parameters None

URL Include the component pathname of the repository in the application path after

/rest/repository/. Include the name of the item type and the identifier of the

specific item at the end of the path.

The following example shows a Legacy REST Web Services request that lists the properties of a specific

repository item of the user item type in the /atg/userprofiling/ProfileAdapterRepository repository.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4;DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc

360 7 Using Legacy REST Web Services

2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 29 Oct 2010 16:40:51 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <repositoryId>130001</repositoryId> <securityStatus>4</securityStatus>

[Additional property values omitted to save space]

<ThirtySomethings>false</ThirtySomethings> <MenOnly>false</MenOnly> <Fashionista>false</Fashionista> <Young>false</Young> <WomenOnly>false</WomenOnly></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Retrieving a Specific Property Using Legacy REST

To retrieve a specific property of a repository item, send a Legacy REST Web Services request as described in the

following table.

Request Component Value

HTTP Method GET

Functional Parameters None

URL Include the component pathname of the repository in the application path after

/rest/repository/. Include the name of the item type, the identifier of the

specific item, and the name of the property at the end of the path.

The following example shows a Legacy REST Web Services request that returns the lastPurchaseDate

property of a specific repository item of the user item type in the atg/userprofiling/

ProfileAdapterRepository repository.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/lastPurchaseDate

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/lastPurchaseDate HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5

7 Using Legacy REST Web Services 361

> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4;DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="A8D99275B90B200E0913A8831E77A9F4" fordomain myserver, path /, expire 0< Set-Cookie: JSESSIONID=A8D99275B90B200E0913A8831E77A9F4; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 29 Oct 2010 19:42:35 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <lastPurchaseDate>2010-10-27</lastPurchaseDate></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Performing RQL Queries in Legacy REST

To perform a Repository Query Language (RQL) query, send a Legacy REST Web Services request as described in

the following table. See information about repository queries in Repository Guide.

Request Component Value

HTTP Method GET

Functional Parameters Include the atg-rest-rql functional parameter. Set its value to the RQL query

you want to execute.

If you include this parameter as a URL query string, make sure that you URL

encode the RQL query. For example, the query ALL RANGE +4 should be

encoded as ALL+RANGE+%2B4.

URL Include the component pathname of the repository item type that you want to

query in the application path after /rest/repository/.

The following example shows a Legacy REST Web Services request that performs an RQL query. It returns the

first four items of item type product in the /atg/commerce/catalog/ProductCatalog repository.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCatalog/product?atg-rest-rql=ALL+RANGE+%2B4

362 7 Using Legacy REST Web Services

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/commerce/catalog/ProductCatalog/product?atg-rest-rql=ALL+RANGE+%2B4 HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=0D62D5F5145D6A1E7A2EDBC669F3BA0F;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 29 Oct 2010 21:33:00 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <product> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod2022</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod1064</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod2024</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod1066</element> </product></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Note: You can include the atg-rest-rql functional parameter in the message body of a POST HTTP request

if you prefer not to URL encode your RQL queries. Use the atg-rest-view control parameter to instruct the

Legacy REST Web Services server to handle your POST request as a GET request. See Handling POST Requests as

Other Methods (page 322).

Note: Do not include parameters in the RQL queries that you perform via the Legacy REST Web Services. Make

sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL

queries in the Repository Guide

Adding a Repository Item in Legacy REST

To add a repository item, send a Legacy REST Web Services request as described in the following table.

Request Component Value

HTTP Method POST

7 Using Legacy REST Web Services 363

Request Component Value

Functional Parameters Include all required property values for the new repository item as functional

parameters with the Legacy REST Web Services request.

URL Include the component pathname of the repository in the application path after

/rest/repository/. Include the name of the item type at the end of the path.

The following example shows a Legacy REST Web Services request that creates a new repository item in the /

atg/userprofiling/ProfileAdapterRepository repository. The returned data includes all the property

values for the new item.

curl -v -b cookies.txt -X POST -H "Content-Type: application/xml" \-d "<parameters><login>rbriere</login><lastName>Briere</lastName><firstName>Roland</firstName><email>rbriere@example.com</email><password>mypassword</password></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=F9C672B8E52D2033A1B70C4EE225577F;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b> Content-Type: application/xml> Content-Length: 168>< HTTP/1.1 201 Created< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 01 Nov 2010 17:35:29 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <repositoryId>130030</repositoryId> <securityStatus>4</securityStatus>

[Additional property values omitted to save space]

<lastPurchaseDate/> <lastName>Briere</lastName> <gender>unknown</gender> <salePriceList/> <categoryLastBrowsed/>

[Additional property values omitted to save space]

364 7 Using Legacy REST Web Services

<registrationDate>2010-11-01 13:35:28.742</registrationDate> <dateOfBirth/> <member>false</member> <firstName>Roland</firstName> <billingAddress/>

[Additional property values omitted to save space]

<Young>false</Young> <WomenOnly>false</WomenOnly></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Transient Items

Use the atg-rest-transient control parameter to create transient repository items. Set the value of the

parameter to true. The following command creates a transient repository item.

curl -v -b cookies.txt -X POST -H "Content-Type: application/xml" \-d "<parameters><login>agold</login><lastName>Gold</lastName><firstName>Abbey</firstName><email>agold@example.com</email><password>mypassword</password></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user?atg-rest-transient=true

Setting Repository Item Properties in Legacy REST

To update properties of a repository item, send a Legacy REST Web Services request as described in the

following table.

Request Component Value

HTTP Method PUT

Functional Parameters Include the new values for each property you are updating as functional

parameters with the Legacy REST Web Services request.

URL Include the component pathname of the repository in the application path after

/rest/repository/. Include the name of the item type and the item identifier

at the end of the path.

The following example shows a Legacy REST Web Services request that updates two properties of an existing

repository item in the /atg/userprofiling/ProfileAdapterRepository repository.

curl -v -b cookies.txt -X PUT \-H "Content-Type: application/xml" \-d "<parameters><middleName>Desire</middleName><email>agoldie@example.com</email></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/

7 Using Legacy REST Web Services 365

ProfileAdapterRepository/user/130034

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> PUT /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130034 HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=B6D3509A03881D9CE1A1370434AD18CB;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b> Content-Type: application/xml> Content-Length: 90>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="6A9888BA9F4035AF606AE7E40A435451" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=6A9888BA9F4035AF606AE7E40A435451; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 01 Nov 2010 19:40:41 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>true</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Deleting a Repository Item in Legacy REST

To delete a specific repository item, send a Legacy REST Web Services request as described in the following

table.

Request Component Value

HTTP Method DELETE

Functional Parameters Include the new values for each property you are updating as functional

parameters with the Legacy REST Web Services request.

URL Include the component pathname of the repository in the application path after

/rest/repository/. Include the name of the item type and the item identifier

at the end of the path.

The following example shows a Legacy REST Web Services request that deletes an existing repository item in the

/atg/userprofiling/ProfileAdapterRepository repository.

366 7 Using Legacy REST Web Services

curl -v -b cookies.txt -X DELETE \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130037

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> DELETE /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130037HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=E8FF855FEF5C59ECF6FA9D1A69F1C30D;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 410 Gone< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 01 Nov 2010 20:21:19 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>true</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Property Filtering with Legacy REST

Legacy REST Web Services include functionality that filters properties from output. Use this functionality to:

• Mark a property in a Nucleus component or repository item as hidden or not writable.

• Configure the system to override the default functionality of outputting all items and instead output only the

items defined in the filtering configuration file.

• Add your own custom properties for components or repository items and specify the sources of their values.

An extension of the property filtering feature, called property aliasing, allows you to create virtual components

with properties that assemble values from a variety of sources.

Default Filtering in Legacy REST

The filtering configuration file is located at /atg/rest/filtering/filteringConfiguration.xml in your

Oracle Commerce Platform server’s configuration path. To customize it, create that file in your own module and

the server’s XML combination functionality will combine all the filteringConfiguration.xml files.

7 Using Legacy REST Web Services 367

Include component elements in the file to configure the filtering applied to requests for Nucleus components

and repositories. Set the name attribute of the component element to a Nucleus component path, a repository

path, or a fully qualified Java class or interface name. If you enter a Java class or interface name, the filtering

behavior will apply to objects that are subclasses or implementations of it. Filters for Nucleus component paths

override filters for Java classes and implementations. Only one filter can apply to a request for an object.

The following sample makes one property hidden and another writable in a Nucleus component and a

repository item:

• property1 and repProperty1 are both hidden and will not be returned in the output whenever the

Nucleus component or that specific property is requested.

• property2 and repProperty2 cannot be changed by a REST request. (Note that the writable flag affects

only REST requests.)

<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> </component>

<component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> </item-descriptor> </component></rest-filtering>

The default-include attribute tells the server that it should return only the values specified inside this

component tag and ignore all other properties of the Nucleus component or repository item.

The following sample adds additional properties which do not exist in the Nucleus component or repository

item. The sample also configures where the values for these “virtual” properties come from.

• The property called virtual1 does not exist in the /some/Component bean. Its value, specified by the

target attribute, is the value of property2 in the same object.

• Similarly, the repVirtual1 property returns the value of repProperty2 as its value.

• The target attribute also allows for subproperties to be specified, as the sample demonstrates for the

virtual2 and repVirtual2 properties. Note that the dot notation can be more than one level deep.

<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> </component>

<component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/>

368 7 Using Legacy REST Web Services

<property name="repVirtual2" target="repProperty2.subproperty"/> </item-descriptor> </component></rest-filtering>

The next sample extends the previous one by adding a component attribute to the property tag and using

that in combination with the target tag. This demonstrates how the value of a property can come from another

Nucleus component. (Note that the component attribute can only reference a Nucleus component.) Dot

notation can be used in the target attribute when the component attribute is used.

<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> <property name="virtual3" component="/some/other/Component" target="aProperty"/> </component>

<component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> <property name="repVirtual3" component="/some/other/Component" target="aProperty"/> </item-descriptor> </component></rest-filtering>

Finally, if you need to write custom code to specify your value, then you must use the property-customizer

attribute, as shown in the following sample.

<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> <property name="virtual3" component="/some/other/Component" target="aProperty"/> <property name="virtual4" property-customizer="some.class.Here"/> </component>

<component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> <property name="repVirtual3" component="/some/other/Component" target="aProperty"/> <property name="repVirtual4" property-customizer="some.class.Here"/> </item-descriptor> </component></rest-filtering>

7 Using Legacy REST Web Services 369

When using the property-customizer attribute, the value should be the name of a class which implements

the atg.rest.filtering.RestPropertyCustomizer interface, shown below.

public Object getPropertyValue(String pPropertyName, Object pResource);

public void setPropertyValue(String pPropertyName, Object pValue, Object pResource);

You can also set the property-customizer attribute to a Nucleus component path. The component must be

an instance of a class that implements the atg.rest.filtering.RestPropertyCustomizer interface.

Specifying the Filter Depth

You can control the nested level at which a filter will be applied. The number of nested levels at which the filter

is applied is the filter depth. A filter depth of zero indicates that the filter should apply only to the immediate

properties of the component the filter is configured for. A filter depth of one indicates that the filter should apply

to the first nested level of properties.

To set the filter depth for a repository, add the depth attribute to the item-descriptor element. For example:

<component name="/atg/userprofiling/ProfileAdapterRepository" default-include="false"> <item-descriptor name="user" depth="1"> <property name="wishlist" hidden="false"/> <property name="creditCards" hidden="false"/> </item-descriptor></component>

To set the filter depth for a non-repository component, add the depth attribute to the component element. For

example:

<component name="/atg/resttest/BeanTest" depth="0" default-include="false"> <property name="repository" hidden="false"/></component>

Filtering Templates with Legacy REST

You can configure property filtering templates that will be applied when REST requests invoke them. Configure

filtering templates for specific Nucleus components, repositories, or Java classes in the /atg/rest/filtering/

filteringConfiguration.xml file, just as you would for default filtering. See Default Filtering in Legacy

REST (page 366).

Include a template element in the rest-filtering element for each template you want to configure. Add

an id attribute to the template element. REST clients will refer to this id value when invoking the template.

Configure the filtering behavior of the template using the same elements and syntax that you would in a

component element for default filtering. See Default Filtering in Legacy REST (page 366).

The following filteringConfiguration.xml file defines a filtering template.

<rest-filtering> <template id="myfiltertemplate" name="/atg/MyDog" default-include="true">

370 7 Using Legacy REST Web Services

<property name="tricks" hidden="true" /> </template></rest-filtering>

Invoke filtering templates with the atg-rest-property-filter-templates control parameter. Include the id of a

template or a JSON array of ids as the value of this parameter.

The following REST request invokes the filtering template configured in the example above.

curl -v -b cookies.txt -X GET \http://myserver:7003/rest/bean/atg/MyDog?atg-rest-property-filter-templates=myfiltertemplate

The following REST request invokes multiple filtering templates.

curl -v -b cookies.txt -X GET \http://myserver:7003/rest/bean/atg/MyDog?atg-rest-property-filter-templates=["userFilter","wishlistFilter"]

Filtering for One Request with Legacy REST

Use the atg-rest-property-filters control parameter to apply property filtering to individual Legacy REST

Web Services requests. The value of the control parameter uses the same format as the rest-filtering element

in the /atg/rest/filtering/filteringConfiguration.xml configuration file. See Default Filtering in

Legacy REST (page 366).

If you include the atg-rest-property-filters control parameter in a REST request, the configurations that

you have made in the filteringConfiguration.xml file will not apply at all. The REST interface considers

only the per-request filter.

If you include the atg-rest-property-filters control parameter in a REST request, all properties are hidden

by default. You must explicitly set the hidden attribute to false for each property that you wish to return.

Use JSON markup for the atg-rest-property-filters value. The components of the JSON value are shown

below.

{ "<componentName>": [ { "item-descriptor": "<itemDescriptorName>", "depth": <depthInt>, "properties": { "<propertyName>": { "hidden": <boolean>, "writable": <boolean>, "target": "<target-dot-notation>", "component": "<component-path>", "property-customizer": "<customizer-class-name>" }, ... }, ... }, ...

7 Using Legacy REST Web Services 371

], ...}

For example, the following atg-rest-property-filters control parameter value specifies that only the

wishlist property will be returned for user repository items. It also specifies that only the eventType and

published values will be returned for the wishlist property.

{ "/atg/userprofiling/ProfileAdapterRepository": [ { "item-descriptor": "user", "depth": 0, "properties": { "wishlist": {

} } } ], "/atg/commerce/gifts/Giftlists": [ { "item-descriptor": "gift-list", "depth": 1, "properties": { "eventType": { }, "published": { } } } ]}

The REST Web Service server will check several configuration parameters before accepting filters supplied

with the atg-rest-property-filters control parameter. These configuration properties control whether certain

types of per-request filtering will be accepted. There are individual configuration properties for requests

that will return JSON and XML output. See information about the following properties in /atg/rest/output/

JSONOutputCustomizer (page 375) and /atg/rest/output/XMLOutputCustomizer (page 376).

• enablePerRequestFilters

• enablePerRequestComponentFilters

• enablePerRequestRepositoryFilters

• enablePerRequestClassFilters

Property Aliasing with Legacy REST

Property aliasing allows you to create virtual components with properties that assemble values from a variety

of sources. Use virtual components to gather data from a variety of sources and return it in a single Legacy REST

Web Services request.

To create a virtual component with property aliasing:

372 7 Using Legacy REST Web Services

1. Add a component element to the /atg/rest/filtering/filteringConfiguration.xml configuration

file for your Oracle Commerce Platform server. Specify the Nucleus path for the virtual component in the

name attribute of that element.

2. Include one or more property elements in the component element. Either draw the value of the component

from another component property using the component and target attributes or from a custom class using

the property-customizer attribute.

The following example configuration creates a virtual component. It specifies the name of a component that

does not exist in the name attribute of the component tag, thus creating a virtual component. When creating

virtual components in this way, do not use the item-descriptor element.

When a REST client requests this component, the list of properties that are specified inside the component

element will be rendered.

<rest-filtering> <component name="/some/nonexisting/Component"> <property name="property1" component="/some/other/Component" target="aProperty"/> <property name="property2" property-customizer="some.class.Here"/> </component><rest-filtering>

Suppressing Property Expansion in Legacy REST

You can configure the Legacy REST Web Services interface to return only the string representation of specific

properties. This can be useful when you need to set the return depth to a level that returns certain deeply-

nested properties but you do not want extensive, unnecessary detail for other properties. See Return

Depth (page 343). Suppress property expansion to return only the string representation.

The following example output shows the string representation of a timestamp value.

"creationDate": "2008-10-21 16:52:00.0"

The following example output shows a timestamp value that has been expanded.

"creationDate": { "class": "class java.sql.Timestamp", "date": 21, "day": 2, "hours": 16, "minutes": 52, "month": 9, "nanos": 0, "seconds": 0, "time": 1224622320000, "timezoneOffset": 240, "year": 108},

See instructions for suppressing property expansion in the following sections:

7 Using Legacy REST Web Services 373

• Suppressing Property Expansion for Java Classes (page 373)

• Suppressing Property Expansion for Specific Properties (page 373)

Suppressing Property Expansion for Java Classes

You can suppress property expansion for properties that have specific Java classes as their data types.

1. Add the fully qualified Java class name of each Java class that you want to suppress property expansion for.

Separate class names with commas.

nonExpandableClassesList=java.util.Date,java.sql.TimeStamp

2. Set the ignoreExpandableOutputForSpecificClasses property of the /atg/rest/filtering/

FilteringManager component to true.

Suppressing Property Expansion for Specific Properties

You can suppress property expansion for specific properties.

1. Add the property to the filteringConfiguration.xml file. See Default Filtering in Legacy REST (page

366).

2. Include the expand attribute in the property element. Set the value of the attribute to false.

<rest-filtering>

<component name="/atg/commerce/catalog/ProductCatalog"

default-include="true">

<item-descriptor name="product">

<property name="creationDate"

expand="false"/>

</item-descriptor>

</component>

</rest-filtering>

Filtering Priority in Legacy REST

You can apply property filtering for Legacy REST requests at three levels: default filtering, filtering templates, and

per-request filtering. The Legacy REST Web Services server gives priority to filters according to these levels in the

following order.

1. Per-request filtering

2. Filtering templates

3. Default filtering

For example, if default filtering specifies that a property should be hidden and a per-request filter specifies that

it is not hidden, the per-request filtering has priority. The property value will be returned in the results.

Configuring the Legacy REST Server

Configure the Legacy REST Web Services by setting the parameters described in the following sections.

374 7 Using Legacy REST Web Services

/atg/rest/Configuration

This section explains configuration properties that are set on the /atg/rest/Configuration Legacy REST

Web Services component.

Property Description

defaultOutputCustomizer This configuration property controls the markup that the Legacy REST

Web Services server uses for returned data. See Choosing Output

Markup (page 335). The following example specifies that the server

should use XML format for the data it returns.

defaultOutputCustomizer=/atg/rest/output/

XMLOutputCustomizer

maxDepthAllowed This configuration property controls the maximum number of nested

property levels that you can expand in returned data. See Expanding

Multiple Values and Complex Objects (page 338). The following

example specifies that only three nested levels may be expanded.

maxDepthAllowed=3

/atg/rest/processor/BeanProcessor

This section explains configuration properties that are set on the /atg/rest/processor/BeanProcessor

component for Legacy REST Web Services.

Property Description

returnFormHandlerExceptionsByDefault This configuration property controls whether the

Legacy REST Web Services server will return information

about the exceptions it encounters while invoking form

handlers. See Returning Legacy REST Form Handler

Exceptions (page 352). The following example specifies

that exceptions should be included in the HTTP response

to a Web Services request.

returnFormHandlerExceptionsByDefault=true

returnFormHandlerPropertiesByDefault This configuration property controls whether the Legacy

REST Web Services server will return the properties of

the form handler components it invokes. See Returning

Legacy REST Form Handler Properties (page 352).

The following example specifies that the form handler

properties should be included in the HTTP response to a

Web Services request.

returnFormHandlerPropertiesByDefault=true

7 Using Legacy REST Web Services 375

/atg/rest/output/JSONOutputCustomizer

This section explains configuration properties that are set on the /atg/rest/output/

JSONOutputCustomizer component for Legacy REST Web Services.

Property Description

enableFormatDateOutput This configuration property specifies whether the Legacy

REST Web Services server will return date properties in the

following format:

MM/dd/yyyy HH:mm:ss z

If this property is set to true, dates will be returned in this

format. If the property is set to false, dates will be returned

as a string representation of the java.util.Date object.

See Date Format in Returned Data (page 344).

enablePerRequestFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that are presented with REST requests. See

Property Filtering with Legacy REST (page 366).

This property affects requests that will return results

formatted with JSON markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

enablePerRequestComponentFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that affect Nucleus components when they are

presented with REST requests. See Property Filtering with

Legacy REST (page 366).

This property affects requests that will return results

formatted with JSON markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

376 7 Using Legacy REST Web Services

Property Description

enablePerRequestRepositoryFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that affect repositories when they are presented

with REST requests. See Property Filtering with Legacy

REST (page 366).

This property affects requests that will return results

formatted with JSON markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

enablePerRequestClassFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that affect components that subclass or

implement specific Java classes when they are presented

with REST requests. See Property Filtering with Legacy

REST (page 366).

This property affects requests that will return results

formatted with JSON markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

showRestPaths This configuration property specifies whether the Legacy

REST Web Services server will return complex property

values as Nucleus paths or by including the actual complex

data in an HTTP response. See Expanding Multiple Values

and Complex Objects (page 338).

Setting the showRestPaths property on the /atg/rest/

output/JSONOutputCustomizer component only affects

returned data that is formatted using JSON markup.

The following example specifies that multiple values and

complex objects should be expanded in returned data.

showRestPaths=false

/atg/rest/output/XMLOutputCustomizer

This section provides information about configuration properties that may be set on the /atg/rest/output/

XMLOutputCustomizer component for Legacy REST Web Services

7 Using Legacy REST Web Services 377

Property Description

enableFormatDateOutput This configuration property specifies whether the Legacy

REST Web Services server will return date properties in the

following format:

MM/dd/yyyy HH:mm:ss z

If this property is set to true, dates will be returned in this

format. If the property is set to false, dates will be returned

as a string representation of the java.util.Date object.

See Date Format in Returned Data (page 344).

enablePerRequestFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that are presented with REST requests. See

Property Filtering with Legacy REST (page 366).

This property affects requests that will return results

formatted with XML markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

enablePerRequestComponentFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that affect Nucleus components when they are

presented with REST requests. See Property Filtering with

Legacy REST (page 366).

This property affects requests that will return results

formatted with XML markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

enablePerRequestRepositoryFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that affect repositories when they are presented

with REST requests. See Property Filtering with Legacy

REST (page 366).

This property affects requests that will return results

formatted with XML markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

378 7 Using Legacy REST Web Services

Property Description

enablePerRequestClassFilters This configuration property controls whether the Legacy

REST Web Services server will accept filtering control

parameters that affect components that subclass or

implement specific Java classes when they are presented

with REST requests. See Property Filtering with Legacy

REST (page 366).

This property affects requests that will return results

formatted with XML markup. See Choosing Output

Markup (page 335).

If this property is set to true, the server will accept the

control parameters. If it is set to false the server will ignore

them.

showRestPaths This configuration property specifies whether the Legacy

REST Web Services server will return complex property

values as Nucleus paths or by including the actual complex

data in an HTTP response. See Expanding Multiple Values

and Complex Objects (page 338).

Setting the showRestPaths property on the /atg/rest/

output/XMLOutputCustomizer component only affects

returned data that is formatted using XML.

The following example specifies that multiple values and

complex objects should be expanded in returned data.

showRestPaths=false

/atg/rest/processor/RepositoryProcessor

This section explains configuration properties that are set on the /atg/rest/processor/

RepositoryProcessor component of the Legacy REST Web Services.

Property Description

acceptJSONInput This configuration property specifies whether the Legacy REST

Web Services server will accept standard JSON markup for setting

collection or map values on repository item properties.

The following example specifies that the Legacy REST Web Services

server will accept JSON markup for setting multiple value repository

item properties.

acceptJSONInput=true

7 Using Legacy REST Web Services 379

Property Description

appendMultiValuesByDefault This configuration property specifies whether the values you set in

repository item properties should be added to an existing set of values

or should replace them. This only applies to repository item properties

that accept multiple values. See Using Multiple Values in Input (page

329).

The following example specifies that values set in a repository item

property that holds multiple values should be added to the existing

list. The existing values will remain set.

appendMultiValuesByDefault=true

/atg/rest/processor/RestSecurityProcessor

This section explains configuration properties that are set on the /atg/rest/processor/

RestSecurityProcessor component of the Legacy REST Web Services.

Property Description

allowAccessForUnsecuredRepository This configuration property specifies whether the

Legacy REST Web Services server will allow clients to

get or set properties in unsecured repositories. Allowing

this access is not recommended in a production

environment. Configure repository security before

allowing Legacy REST Web Services clients to interact

with repositories. See Repository Security in Legacy

REST (page 382).

The following example specifies that any Legacy

REST Web Services client may get or set properties in

unsecured repositories. Use this setting for testing only.

allowAccessForUnsecuredRepository=true

Security for Legacy REST Web Services

This section provides information about the way the Legacy REST Web Services server secures its interface and

how it interacts with the underlying security system for the Oracle Commerce Platform in general.

Legacy REST Security Overview

The Legacy REST Web Services server uses the underlying security system of the Oracle Commerce Platform.

HTTP clients that invoke Legacy REST Web Services functionality behave in a manner that is similar to human

users logging into an Oracle Commerce Platform user interface and interacting with its functionality.

380 7 Using Legacy REST Web Services

To understand the security system used by the Legacy REST Web Services server you must understand the

system used by the Oracle Commerce Platform. See Managing Access Control in the Platform Programming Guide.

Logging In and Session IDs

The Legacy REST Web Services server will only process requests if the HTTP client sending them has an active

HTTP session. Clients must log in to the server before performing operations. The server will provide a session ID

which the client must present with each Legacy REST Web Services request. See Logging In (page 323).

Nucleus Component Granularity

The security functionality for Legacy REST Web Services allows security to be placed on multiple levels of

granularity for Nucleus components.

The default configuration for Legacy REST Web Services is to not allow access to any components. This means

that you will need to configure security to be able to call methods or access properties on Nucleus components.

Security on Nucleus components can be configured globally for all components, at the component level for

all properties and methods, at the property level, at the method level, and for entire Nucleus sub-trees. The

REST security subsystem depends on the Oracle Commerce Platform security system and therefore uses ACLs

which are similar to those used to configure security in other parts of an Oracle Commerce Platform server.

The personas can be users, organizations, or roles. The valid rights which can be assigned to a persona are

read, write, and execute. Read and write refer to Nucleus properties and execute refers to Nucleus methods. To

configure multiple personas, use a semicolon (;) character to separate each access control entry (persona/rights).

The REST security configuration file is located at /atg/rest/security/restSecurityConfiguration.xml.

To add your own security configuration create a file at that location in the config directory of your module.

Note: The Legacy REST Web Services module does not provide functionality for securing repository items All

Oracle Commerce Platform repository security is handled by the Oracle Commerce Platform secured repository

system, which works in conjunction with the Oracle Commerce Platform Security System to provide fine-grained

access control to repository item descriptors, individual repository items, and even individual properties. For

more information, see the Repository Guide.

Quick Setup for Testing Legacy REST

Once the server is running with the REST module, your platform is now able to accept and process REST

requests. Before you begin coding, you must configure the Web Services security component. By default:

• The security components in the Legacy REST Web Services require you to be logged into the server in order to

make calls.

• No users have access to any components, so even a logged-in user will not be able to successfully make any

REST requests.

In a development environment, you can set a default ACL in the security configuration file. This allows all the

specified users to have access to all Nucleus components.

Important: This functionality is provided for convenience and should not be used in a production environment

unless that is the specified intent.

To set a default ACL in the security configuration layer, create a file in your localconfig directory at atg/

rest/security named restSecurityConfiguration.xml. Add the following lines to the file, replacing

#username# with the name of a valid profile for logging onto your Oracle Commerce Platform system.

<rest-security>

7 Using Legacy REST Web Services 381

<default-acl value="Profile$login$#username#:read,write,execute"/></rest-security>

Global Security with Legacy REST

To configure global security, use the default-acl tag. This tag defines which personas have access to Nucleus

components. In the following example, all users who are assigned the restUser role have read and write

access to all Nucleus properties and execute access for all methods on Nucleus components. The default-

acl tag is optional. This example assumes that a role called restUser has already been created in the profile

repository.

<rest-security> <default-acl value="Profile$role$restUser:read,write,execute"/> </rest-security>

Component Security in Legacy REST

To configure security on a specific component, use the resource tag. This tag, along with the component

attribute, allows you to define which users have access to the specified component. You could disable security

entirely for the specified component by using the optional secure attribute.

In the following example, the /some/Component component is configured so that only the user whose login

is restAdmin has full access to it; users with the restUser role only have read access. In addition, the /some/

other/Component component is configured to disable security.

<rest-security> <default-acl value="Profile$role$restUser:read,write,execute"/>

<resource component="/some/Component"> <default-acl value="Profile$login$restAdmin:read,write,execute; Profile$role$restUser:read"/> </resource>

<resource component="/some/other/Component" secure="false"/></resource></rest-security>

Property and Method Security in Legacy REST

To configure security on a component property or method, add a property or method tag within the resource

tag. The property and method tags allow you to control which users have access to specific properties and

methods.

By default, properties and methods of unsecured components are secured. You must explicitly list any

properties or methods that you want to expose. In the following example, the property named Property1

would default to being a secure property, however, we want that property to be accessible only to the

restAdmin, so it must be identified specifically. The property named Property2 is available to everyone since

it does not specify an ACL value. However, all other properties and methods of this component are secure by

default. Note that this does not affect what is returned by the URL, only which URLs are accessible.

382 7 Using Legacy REST Web Services

<rest-security> <default-acl>Profile$role$restUser:read,write,execute"</default-acl>

<resource component="/some/Component"> <default-acl value="Profile$login$restAdmin:read,write,execute; Profile$role$restUser:read"/>

<property name="property1"> <acl value="Profile$login$restAdmin:read,write"/> </property>

<property name="property2" secure="false"/> <method name="methodA"> <acl value="Profile$login$restAdmin:execute"/> </method> </property>

<method name="methodB" secure="false"/> </resource>

<resource component="/some/other/Component" secure="false"/> </resource></rest-security>

Methods which are overloaded and have different security requirements require a signature attribute,

available on the method tag. This attribute allows for a Java method signature that uniquely identifies the

method.

Repository Security in Legacy REST

The Legacy REST Web Services module does not provide functionality for securing repository items. If you need

to provide access to repository data to Legacy REST Web Services clients, use one of the following options:

• Implement a Java Server Page (JSP) to access and return the repository data to REST clients. See Invoking Java

Server Pages (JSPs) with Legacy REST (page 354). If your JSP provides access to sensitive resources, make

sure to include security measures such as an access control servlet in your Web application.

• Use the secured repository system, which works in conjunction with the Oracle Commerce Platform security

system to provide fine-grained access control to repository item descriptors, individual repository items, and

even individual properties. For more information, refer to the Repository Guide

Securing Groups of Components in Legacy REST

The Legacy REST Web Services provide the ability to secure groups of components within the same Nucleus sub-

tree. This is accomplished by using the * wildcard character. Note that * is the only wildcard character allowed.

The following example sets the ACL for all components within the /atg/commerce sub tree to be accessible

only by users with the restCommerceUser role.

<rest-security> <default-acl>Profile$role$restUser:read,write,execute"</default-acl>

<resource component="/atg/commerce/*">

7 Using Legacy REST Web Services 383

<default-acl value="Profile$role$restCommerceUser:read,write,execute"/> </resource></rest-security>

384 7 Using Legacy REST Web Services

8 Legacy Rest Client Libraries 385

8 Legacy Rest Client Libraries

The Legacy REST Web Services package includes two client libraries:

• Java Client Library for Legacy REST (page 385)

• ActionScript Client Library for Legacy REST (page 399)

These libraries make Legacy REST Web Services easier to use by hiding the complexity of creating connections,

assembling payloads for requests, and processing responses.

Java Client Library for Legacy REST

The Java client library provides a number of classes that assist in making REST calls to the Legacy REST Web

Services.

The following classes are the ones you may use the most often:

• RestSession - Handles login and logout, manages connections, and issues requests.

• RestResult - Accesses the RestResult object that is returned when a request is made to the server. This

class also includes convenience methods for retrieving the response data.

• RestComponentHelper - Contains a series of static helper methods that simplify issuing Nucleus component

calls to the server.

• RestRepositoryHelper - Contains a series of static helper methods that simplify issuing repository calls to

the server.

Creating Requests

It easiest to make most Legacy REST Web Services requests with the RestComponentHelper and

RestRepositoryHelper classes. These two classes simplify calling into the server by providing methods which

hide the complexity of assembling the data for the request. All the methods for both classes are static and each

returns a RestResult object and throws RestClientException. See the JavaDoc for more information about

each method.

atg.rest.client.RestComponentHelper

The methods of the RestComponentHelper class allow access to components, properties, and methods. Each

of the methods accepts a Map of parameters, which control the request. For more information and examples,

see Accessing Components with the Java Client Library (page 394).

386 8 Legacy Rest Client Libraries

• public static RestResult getComponent(String pComponentPath, Map<String,Object>

pParams, RestSession pSession)

Returns all the properties of the specified Nucleus component.

• public static RestResult getPropertyValue(String pComponentPath, String pProperty,

Map<String,Object> pParams, RestSession pSession)

Returns the requested property from the specified Nucleus component.

• public static RestResult setPropertyValue(String pComponentPath, String pProperty,

Object pValue, Map<String,Object> pParams, RestSession pSession)

Sets a value on the specified Nucleus component property.

• public static RestResult executeMethod(String pComponentPath, String pMethodName,

Object[] pArguments, Map<String,Object> pParams, RestSession pSession)

Calls a public method on the specified Nucleus component.

The Object[] pArguments parameter is an array of method arguments. This parameter should

contain one Object for each of the method parameters. For example, if the method takes an int, then a

java.lang.Integer object should be passed. The Java client library handles converting the object for

transport to the server and the Legacy REST module handles converting it to an int. If any parameter object

is passed as a String, the parameter will be transported to the server without any changes. This means that

a method that takes an int can have a java.lang.String object with a value of 2, for example, passed. For

parameters that are complex objects, the object can be passed as a parameter and the library will attempt

to convert it for transport. When the request is sent to the server, a new instance will be constructed and its

properties populated with the values from the original object. Collections and Maps can also be transported.

For more information, see Calling Methods with the Java Client Library (page 394).

atg.rest.client.RestRepositoryHelper Class

The methods of the RestRepositoryHelper class allow you to access repository items, execute RQL queries,

retrieve individual property values, set property values, create items, and remove items. Each of the methods

takes a Nucleus repository path and item descriptor name as its first two arguments, as well as a Map of

parameters, which control various aspects of the request. For more information and examples, see Accessing

Repository Items with the Java Client Library (page 396).

• public static RestResult createItem(String pRepositoryPath, String

pItemDescriptorName, Map<String,Object> pParams, RestSession pSession)

Returns the ID of the newly created repository item.

• public static RestResult createItem(String pRepositoryPath, String

pItemDescriptorName, String pItemId, Map<String,Object> pParams, RestSession

pSession)

Returns the ID of the newly created repository item.

• public static RestResult removeItem(String pRepositoryPath, String

pItemDescriptorName, String pItemId, Map<String,Object> pParams, RestSession

pSession)

Returns true if the repository item was successfully removed; otherwise, returns false.

• public static RestResult getItem(String pRepositoryPath, String pItemDescriptorName,

String pItemId, Map<String,Object> pParams, RestSession pSession)

8 Legacy Rest Client Libraries 387

Returns the contents of the repository item. If any of the properties are references to other items, Collections,

arrays, or Maps, returns a REST URL that you can use to access the contents of the specific property. You can

create a raw REST request to access the data for the property. For more information, see Creating a Raw REST

Request (page 392).

• public static RestResult getItems(String pRepositoryPath, String

pItemDescriptorName, Map<String,Object> pParams, RestSession pSession)

Returns a series of URLs, one for each item which is being returned. T to control the number of items returned,

the atg-rest-index and atg-rest-count parameters can be passed into the pParams argument.

• public static RestResult executeRQLQuery(String pRepositoryPath, String

pItemDescriptorName, String pRQL, Map<String,Object> pParams, RestSession pSession)

Returns a series of URLs, one for each item which is being returned. To control the number of items returned,

the atg-rest-index and atg-rest-count parameters can be passed into the pParams argument.

Note: Do not include parameters in the RQL queries that you perform via the Legacy REST Web Services. Make

sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL

queries in the Repository Guide.

• public static RestResult getPropertyValue(String pRepositoryPath, String

pItemDescriptorName, String pItemId, String pProperty, Map<String,Object> pParams,

RestSession pSession)

Returns the value of the requested property. If the property is a Collection, Map, array, or reference to another

repository item, returns a URL.

• public static RestResult setPropertyValue(String pRepositoryPath, String

pItemDescriptorName, String pItemId, String pProperty, Object pValue,

Map<String,Object> pParams, RestSession pSession)

Creating a RestSession Object

The Legacy REST Web Services calls are executed within the context of an HTTP session. This enables a client

application to maintain state across requests and to use login information for security purposes.

The RestSession class contains all the logic required for connecting and communicating with an Oracle

Commerce Platform server.

The following code creates a new RestSession object:

RestSession session = RestSession.createSession(host, port, username, password);

Note: You can perform multiple Legacy REST Web Services requests during an HTTP session. See information

about HTTP sessions and the Legacy REST Web Services server in Logging In (page 323).

RestSession class properties

The RestSession class includes the following properties. Some are set when the object is created and others

can be changed after the object has been constructed:

388 8 Legacy Rest Client Libraries

Property Description

Hostname The name of the host which the session will or is connected to. Default is

localhost.

Port The port number which the session will use. Default is 80.

Username The username the session will use to connect.

Password The password the session will use to connect.

Scheme The scheme the session will use to connect. Default is HTTP expect for login

calls.

restContextRoot The Web application context root for Legacy REST Web Services. Default is /

rest.

useInternalProfileForLoginTells the session object to login as an internal user instead of a profile user. You

will probably need to change this property after the RestSession object is

created and before login is called. When connecting to a server that can be

accessed only by internal users, this property must be set to true or the login

will fail.

useHttpsForLogin Tells the session object to use the HTTPS scheme for login calls. Default is true.

httpsPort The HTTPS port number which the session will use. Default is 443.

userId The userId of the connected user. This value is set after logging in.

sessionId The session ID of the current session. This value is set after logging in.

Encoding The encoding to use when encoding parameter values. Default is UTF

inputFormat The default input format that is set on the server. Changing this value has no

effect on the server.

outputFormat The default output format that is set on the server. Changing this value has no

effect on the server

Starting a REST Session

When you start a REST session, the Legacy REST interface sets the session confirmation number, session id, and

the default input and output customizers.

Start a session by doing one of the following:

• Log in to the Legacy REST interface. See Logging in and Logging Out with the Java Client Library (page 389).

• Invoke the RestSession.startSession() method. This will start the session but does not authenticate the

client for access to secured Oracle Commerce Platform components. See Starting a Session Without Logging

In (page 390).

8 Legacy Rest Client Libraries 389

Logging in and Logging Out with the Java Client Library

The following code sample is a shell of a simple application. It does nothing more than login and logout. The

most interesting portion of the following code sample is the execute method.

Note: You can perform multiple Legacy REST Web Services requests during an HTTP session. See information

about HTTP sessions and the Legacy REST Web Services server in Logging In (page 323).

The sample first creates a RestSession object. It does this by calling the static

RestSession.createSession() method. The parameters to createSession are the hostname, port,

username, and password. By default all login calls are issued with HTTPS. If you do not want this functionality,

set the value of the useHttpsForLogin flag to false on the session object, as the following sample does. The

next section of code calls the login() method on the RestSession object. If the login attempt fails, then

a RestClientException is thrown. The last section of code calls the logout() method and concludes the

session.

import atg.rest.client.RestClientException; import atg.rest.client.RestComponentHelper; import atg.rest.client.RestResult; import atg.rest.client.RestSession;

import java.io.IOException;

public class RestClientSample {private String mUsername = null;private String mPassword = null;private String mHost = "localhost";private int mPort = 80;private RestSession mSession = null;

public RestClientSample() {}

protected void parseArguments(String[] pArgs) throws Exception { for (int i = 0; i < pArgs.length; i++) { String arg = pArgs[i];

if (arg.equals("-user")) mUsername = pArgs[i+1]; else if (arg.equals("-password")) mPassword = pArgs[i+1]; else if (arg.equals("-host")) mHost = pArgs[i+1]; else if (arg.equals("-port")) mPort = Integer.parseInt(pArgs[i+1]); }

if (isBlank(mUsername)) throw new Exception("Must supply username"); if (isBlank(mPassword)) throw new Exception("Must supply password");}

protected boolean isBlank(String pStr) { return (pStr == null || pStr.length() == 0 || pStr.trim().length() == 0);}

protected void println(String s) { System.out.println(s);

390 8 Legacy Rest Client Libraries

}

protected void println(Throwable t) { t.printStackTrace(System.out);}

protected void execute() throws RestClientException { mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword); mSession.setUseHttpsForLogin(false);

try { String loginStatus = mSession.login(); if(loginStatus == null || "null".equals(loginStatus)) { mSession = null; System.out.println("Login Failed"); } else { System.out.println("Login Successful"); } }

catch (Throwable t) { println(t); }

finally { try { if(mSession != null) { mSession.logout(); System.out.println("Logout Successful"); } } catch (RestClientException e) { println(e); } }}

/** * @param args */public static void main(String[] args) { RestClientSample sample = new RestClientSample();

try { sample.parseArguments(args); sample.execute(); } catch (Throwable t) { sample.println(t); }} }

Starting a Session Without Logging In

Use the RestSession.startSession() method to start a REST session without authenticating the client. You

can log into the REST server after you start the session if that is required.

8 Legacy Rest Client Libraries 391

Note: Starting a session without logging in will not give your REST client access to secured Oracle Commerce

Platform resources.

The following sample program starts a REST session using the startSession() method.

import atg.rest.client.RestClientException;import atg.rest.client.RestSession;public class RestClientStartSession { // Use your own hostname and port. private String mHost = "myserver"; private int mPort = 9876; private RestSession mSession = null; public RestClientStartSession() {}

protected void execute() throws RestClientException {

// Create a RestSession object. Use the constructor that // takes only the REST server host and port. mSession = RestSession.createSession(mHost, mPort);

// Invoke the startSession() method. mSession.startSession();

// Verify that the session is started. String sessionid = mSession.getSessionId(); System.out.println("The session ID is: " + sessionid);

// perform unsecured operations or login here // forexample: // mSession.login("myusername","mypassword") }

public static void main(String[] args) { RestClientStartSession sample = new RestClientStartSession(); try { sample.execute(); } catch (Throwable t) { t.printStackTrace(System.out); } }}

Accessing Data from the Server

Now you can build on the previous example by accessing a Nucleus component property.

The example that follows makes a request for all the properties of a Nucleus component using the

RestComponentHelper class. This class has several static convenience methods which assist in creating the

requests and issuing them to the server. The getComponent() method take the path to a Nucleus component,

a map of optional parameters, and the RestSession object and returns a RestResult object.

The RestResult object can be used to access the data from the response. The following sample calls

readInputStream() to return a String of the response data. In this case, you can assume that the server is

using the default output format which is JSON. The string in response data will contain the JSON output. A JSON

object is then constructed and output.

392 8 Legacy Rest Client Libraries

Another alternative is to simply output responseData, but this sample illustrates how you might use the

output. Similarly, if the output format was XML, you could create an XML document object using dom4j.

The finally block includes a call to close the result. Doing this will release the underlying connection

resources. If this call is omitted, the next call to the server using the same RestSession object will close the

result.

protected void execute() throws RestClientException { RestResult result = null;

mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword); mSession.setUseHttpsForLogin(false);

try {mSession.login();println("Login Successful");

result = RestComponentHelper.getComponent("/atg/dynamo/Configuration", null,mSession);String responseData = result.readInputStream();if (responseData != null) { JSONObject json = new JSONObject(responseData); println(json.toString());} } catch (Throwable t) {println(t); } finally {if (result != null) result.close();

try { mSession.logout(); println("Logout Successful");}catch (RestClientException e) { println(e);} } }

Creating a Raw REST Request

The RestComponentHelper and RestRepositoryHelper classes might not support every type of request you

want to issue to the server. If this is the case, you can issue a request using the createHttpRequest() method

of the RestSession class. There are two versions of this method:

public RestResult createHttpRequest(String pURL, Map<String,Object>pParams, String pMethodType)

public RestResult createHttpRequest(String pURL, Map<String,Object>pParams, Object[] pArguments, String pMethodType)

8 Legacy Rest Client Libraries 393

The following table describes the arguments for each version of this method.

Argument Description

pURL The URL to request, formatted as

http://hostname:port/uri

The pURL argument must be an absolute URL, including the hostname (and

port, if it is not 80). The RestSession class includes a convenience method

called getHostString() which returns a string containing the scheme, host,

and port number. The caller can then append the remainder of the URL and

pass the resulting string as the first argument to this method.

pParams A Map of parameters to submit along with the request.

This argument is the same as it would have been if you made the request using

either of the helper classes. It contains parameters which can control certain

aspects of the request.

pArguments An array of Objects which contain the method parameter values.

Use this argument only for method calls.

The value is the same as it would be if calling the executeMethod() method

on the RestComponentHelper class.

pMethodType The HTTP method for the request: GET, POST, PUT, or DELETE.

The atg.rest.client.RestConstants class contains constant values for

these strings. In short, GET should be used when retrieving data, POST should

be used when calling methods, PUT should be used when setting properties,

and DELETE is used for deleting repository items. DELETE is not used when

interacting with Nucleus components.

Handling Results

createHttpRequest() and all the helper class methods return a RestResult object that allows

access to various parts of the response. The most interesting and useful method on the RestResult is

readInputStream(). This is a convenience method which will return the response data into a String

public String readInputStream() throws IOException

After calling this method the String object which is returned will contain the JSON or XML with the content

which was requested. The REST module uses the org.json.jar library and the dom4j XML library internally.

You can also use these libraries, or comparable libraries, in your applications.

If the response data is large, you can access the input stream directly by calling getInputStream() on the

RestResult.

394 8 Legacy Rest Client Libraries

Other useful methods on the RestResult object are getResponseCode() and getResponseMessage().

These return the response’s response code and message, respectively. For more information, see HTTP Status

Codes (page 57).

The Java client library uses the java.net.HttpURLConnection class to communicate with servers. To access

any functionality that the RestResult does not expose, call the getConnection() method to return the

underlying HttpURLConnection object.

When you are finished with the RestResult object, it is good practice to call the close() method. This

releases any resources that the HttpURLConnection might hold. If the connection is not closed, the next

request to the server will close the HttpURLConnection.

Accessing Components with the Java Client Library

This section explains how to work with components using the Java client library for the Legacy REST Web

Services.

Getting Component Data

The getComponent() method of the RestComponentHelper class returns a data stream that contains a

representation of a component.

The following code sample returns the Configuration component:

RestResult result = RestComponentHelper.getComponent("/atg/dynamo/Configuration",null, mSession)

Getting and Setting Property Values

The getPropertyValue() method of the RestComponentHelper class returns a data stream that contains the

value of the specified property.

The following code sample gets the value of the property httpPort from the Configuration component.

RestResult result = RestComponentHelper.getPropertyValue("/atg/dynamo/Configuration", "httpPort", params, session)

Use the RestComponentHelper.setPropertyValue() method to set property values on Nucleus

components. The following code sample sets the value of the Configuration component property httpPort to

8580.

RestResult result = RestComponentHelper.setPropertyValue("/atg/dynamo/Configuration", "httpPort", "8580", params, session)

Calling Methods with the Java Client Library

You can use the Legacy REST Web Services to call public methods on Nucleus components. If a method

is overloaded, then the server will attempt to determine which method to call by looking at the

number of arguments supplied. It is also possible to supply a method signature as a parameter to the

RestComponentHelper.executeMethod() method. Supplying the atg-rest-method parameter allows

8 Legacy Rest Client Libraries 395

you to specify the exact method to be called. The value of the parameter should be the Java method signature

of the method to call. You can find the method signature for a method by using the javap command, which

disassembles a class file. (The javap command is part of the JDK.)

Depending on the return type of the method, the output will vary. If the output is an object, then it will return a

JSON or XML stream which contains the values of all the properties in the object. If it is a simple type like an int

or a String, it will return the value. The identifier for the return type is atgResponse.

Passing Parameters to Methods

If you use the Java or ActionScript client libraries that ship with the Legacy REST Web Services, passing

parameters to methods is as simple as supplying the Objects in the pArguments argument for the

RestComponentHelper.executeMethod() method.

If one of the parameters is a simple type, then it should be wrapped in an object. For example, an int will

become a java.lang.Integer, a boolean becomes a java.lang.Boolean, and so on.

When you pass collections, Maps, and arrays as parameters, the client library attempts to convert those types.

Date, Time, and Timestamp objects can also be passed, as shown in the following sample.

RestResult result = RestComponentHelper.executeMethod("/some/Component","aMethod", new Object[] {1,2,3,4.4,5.5,true,'a',0xa}, null, session)

In order to pass repository items, use a preformatted string that takes the format of

repository Nucleus path:item descriptor name:item id

For example:

/atg/commerce/catalog/ProductCatalog:product:prod12345

When you reference a repository item this way, the server performs a lookup and uses the item as the method

argument. For example:

RestResult result = RestComponentHelper.executeMethod("/some/Component","aMethod", new Object[] {"/atg/commerce/catalog/ProductCatalog:product:prod12345"}, null, session)

If a method takes a GenericService as an argument, simply passing the Nucleus path as a string will cause the

server to lookup the Nucleus component and use it as the method argument. For example:

RestResult result = RestComponentHelper.executeMethod("/some/Component","aMethod", new Object[] {"/atg/dynamo/Configuration"}, null, session)

If passing a complex Java object, attempt to add the object to the pArguments argument and call the method.

In most cases, the argument will not need to be transformed before it is transported to the server. The client

library will make an attempt at converting the object for you.

MyObject myObject = new MyObject();RestResult result = RestComponentHelper.executeMethod("/some/Component","aMethod", new Object[] {myObject}, null, session)

396 8 Legacy Rest Client Libraries

Calling Handler Methods

Form handlers use special handler methods for linking form elements with Nucleus components. One of the

more powerful features in the Legacy REST Web Services module is the ability to call handler methods. If

you have existing JSP-based applications, all the functionality which has previously been exposed in those

applications can be reused with REST based applications. Use RestComponentHelper.executeMethod() to

call handler methods.

Keep the following in mind when calling a handler method

• The method name, the second argument in the executeMethod() method, should not contain the “handle”

prefix. For example, to call the handleCreate method, it should be specified simply as create in the

pMethodName argument.

• The pArguments parameter should always be null when you call a handler method.

The following code sample calls the handleCreate method on a specified form handler:

RestResult result = RestComponentHelper.executeMethod("/some/FormHandler","create", null, null, session)

As long as a form handler does not submit a redirect, the execution would be similar to a regular method call.

For those form handler methods which do redirect, the redirect will be intercepted and returned back to the

client as an exception.

Passing Parameters to Form Handlers

Form handler parameters which need to be supplied should be added to the params argument. In a JSP page

these parameters would be the input tags in a JSP form. The following example calls the handleCreate()

method on a form handler. The inputs to the form handler are a first and last name.

Map<String,String> params = new HashMap<String,String>();params.put("firstName", "Andy");params.put("lastName", "Jones");RestResult result = RestComponentHelper.executeMethod("/some/FormHandler","create", null, params, session);

Accessing Repository Items with the Java Client Library

The Legacy REST Web Services RestRepositoryHelper class exposes methods that perform basic Repository

operations.

Getting Repository Items with the Java Client Library

The getItem() method of the RestRepositoryHelper class returns a data stream that contains all the

property values of a repository item.

The following code sample returns an array of URLs. Issuing a request using the

RestSession.createHttpRequest() method returns the property values of the requested item.

RestResult result = RestRepositoryHelper.getItem("/atg/commerce/catalog/ProductCatalog", "product", productId, params, session)

8 Legacy Rest Client Libraries 397

The getItems() method retrieves multiple repository items of the same type in a single call. The following

code sample returns an array of URLs:

RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog", "product", params, session)

When a getItems() call returns many items, you can control the number of items returned with the atg-

rest-index and atg-rest-count parameters. The atg-rest-index parameter tells the server which item to

return first. The atg-rest-count parameter tells the server how many items past the index item to return.

In the following code sample, the first query, with an index of 0 and a count of 10, retrieves 10 items at a time.

The next query has an index of 10 and a count of 10, third, index of 20 and count of 10, and so on.

Map<String,String> params = new HashMap<String,String>();params.put(RestConstants.COUNT, 10);params.put(RestConstants.INDEX, 0);RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog", "product", params, session);

params.put(RestConstants.INDEX, 10);

result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog","product", params, session);

params.put(RestConstants.INDEX, 20);

result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog","product", params, session);

Repository IDs

Each repository item has a unique identifier, called a repository ID. Depending on the repository’s configuration,

the repository ID might not be exposed as a property of the repository item. However, when a repository item

is returned with a REST RepositoryHelper method, you can reliably retrieve its repositoryID by getting the

value of the repositoryId property.

Adding Repository Items

Create a repository item by calling the RestRepositoryHelper.createItem() method. You can supply a

repository ID for the newly created item or you can allow the server to generate a repository ID for you.

A createItem() call returns a data stream that contains all the properties of the created item. This is the same

data stream that is returned when you call RestRepositoryHelper.getItem().

The following code sample adds a repository item and allows the server to generate the repository ID:

RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/ProductCatalog", "product", params, session);

The following code sample adds a repository item and specifies the value of myProductId-12345 as the

repository ID:

RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/

398 8 Legacy Rest Client Libraries

ProductCatalog", "product", "myProductId-12345", params, session);

Deleting Repository Items

Remove a repository item by calling the RestRepositoryHelper.removeItem() method. A removeItem()

call returns a data stream that contains the string true if the item was removed. If the item was not removed,

the call throws an exception.

The following sample removes a repository item:

RestResult result = RestRepositoryHelper.removeItem("/atg/commerce/catalog/ProductCatalog", "product", "myProductId-12345", params, session);

Getting Repository Item Properties with the Java Client

The getPropertyValue() method of the RestRepositoryHelper class returns a data stream that contains

the value of the specified property.

The following sample gets the property value displayName from the product repository item.

RestResult result = RestRepositoryHelper.getPropertyValue("/atg/commerce/catalog/ProductCatalog", "product", "prod12345", "displayName", params, session);

Setting Repository Item Properties with the Java Client

The setPropertyValue() method of the RestRepositoryHelper class sets the value of the specified

property.

The following sample sets the property displayName to the string My Modified Display Name.

RestResult result = RestRepositoryHelper.setPropertyValue("/atg/commerce/catalog/ProductCatalog", "product", "prod12345", "displayName","My Modified Display Name", params, session);

Performing Queries for Repository Items

Performing queries for repository items using RQL is similar to retrieving them with getItems(),

but querying provides for more control over the items included in the results. Use the

RestRepositoryHelper.executeRQLQuery() method to execute and RQL query.

To request a range of items, use the atg-rest-index and atg-rest-count parameters with the

executeRQLQuery() method, just as you’d use them with getItems(). See Retrieving a Repository Item in

Legacy REST (page 359) for more information.

In the following example, the INDEX and COUNT keywords in the RQL language are used instead of the “atg-rest-

index” and “atg-rest-count” parameters.

Map<String,String> params = new HashMap<String,String>();params.put(RestConstants.COUNT, 10);params.put(RestConstants.INDEX, 0);RestResult result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);

8 Legacy Rest Client Libraries 399

params.put(RestConstants.INDEX, 10);result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);

params.put(RestConstants.INDEX, 20);result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);

Using the Java Client in Android Applications

The Java REST client includes the class AndroidIntrospectorService which implements

atg.rest.client.beans.IntrospectorService. This class is a replacement for the

java.beans.Introspector class, which does not work on Android devices.

To use the Java REST client in an Android application, include the following file in the application’s Java class

path.

META-INF/services/atg.rest.client.beans.IntrospectorService

Include the following content in the file:

atg.rest.client.beans.AndroidIntrospectorService

ActionScript Client Library for Legacy REST

ActionScript is the programming language for the Adobe Flash Player run-time environment. This library is

useful for client applications written in Adobe Flash or Adobe Flex.

Note: Legacy REST Web Services were tested with ActionScript 3.

The ActionScript client library is nearly identical in structure to the Java client library. The main difference

between the two libraries is the way they handle results:

• The Java client library uses the RestResult class to handle results.

• The ActionScript library does not include a RestResult class; instead, it handles results using a callback

mechanism. Therefore, helper class methods and the createHttpRequest() method for the ActionScript

client library take a result handler and fault/error handler functions as arguments.

The following code sample illustrates how the ActionScript client library handles results.

public function getPropertyValue():void {RestComponentHelper.getPropertyValue("/atg/dynamo/Configuration", "httpPort",null, session, handleResult, handleFault);// get the httpPort property from the Configuration component}

400 8 Legacy Rest Client Libraries

public function handleResult(pEvent:Event):void { var xml:XML = new XML(pEvent.target.data);// create an XML object populateGridWithXML(xml);// populate the control with the XML output}

public function handleFault(pEvent:Event):void { Alert.show("Fault");// display an error dialog}

atg.rest.client.RestComponentHelper

The RestComponentHelper class simplifies Nucleus requests.

The RestComponentHelper methods are written in ActionScript as follows. For details about individual class

methods, refer to the Java Client Library for Legacy REST (page 385) section.

public static function getComponent(pComponentPath:String, pParams:Array,pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function getPropertyValue(pComponentPath:String, pProperty:String,pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function setPropertyValue(pComponentPath:String, pProperty:String,pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function executeMethod(pComponentPath:String, pMethodName:String,pArguments:Array, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void

atg.rest.client.RestRepositoryHelper

The RestRepositoryHelper class simplifies repository requests.

The RestRepositoryHelper class methods are written in ActionScript as follows. For details about individual

class methods, refer to the Java Client Library for Legacy REST (page 385) section.

public static function getItem(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler: Function):voidpublic static function getItems(pRepositoryPath:String, pItemDescriptorName:String, pParams:Object, pSession:RestSession, pResultHandler:Function,pFaultHandler:Function):voidpublic static function executeRQLQuery(pRepositoryPath:String,pItemDescriptorName:String, pRQL:String, pParams:Object, pSession:RestSession,pResultHandler:Function, pFaultHandler: Function):voidpublic static function getPropertyValue(pRepositoryPath:String,pItemDescriptorName:String, pItemId:String, pProperty:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void

8 Legacy Rest Client Libraries 401

public static function setPropertyValue(pRepositoryPath:String,pItemDescriptorName:String, pItemId:String, pProperty:String, pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function,pFaultHandler:Function):voidpublic static function createItem(pRepositoryPath:String,pItemDescriptorName:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function createItemWithId(pRepositoryPath:String,pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function removeItem(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler: Function):void

Calling Methods with ActionScript

The ActionScript client library’s RestClientHelper class includes the following helper methods, which convert

arrays, Lists, and Objects to Multivalue objects:

public static function convertArrayToMultivalue(pValue:Array, pMultiValueType:String, pComponentType:String, pFormat:String, pSession:RestSession):Stringpublic static function convertIListToMultivalue(pValue:IList, pMultiValueType:String, pComponentType:String, pFormat:String, pSession:RestSession):Stringpublic static function convertObjectToMultivalue(pValue:Object, pMultiValueType:String, pKeyType:String, pValueType:String, pFormat:String, pSession:RestSession):String

The following table describes the arguments for each of these methods.

Argument Description

pMultiValueType The absolute path of a Java class, such as java.util.ArrayList. Be sure to specify

a valid class name and not an interface name.

pComponentType The class type of the component to instantiate for each element in the multivalve

type. For example, an array of integers in ActionScript could be converted to an

ArrayList of java.lang.Integer objects.

pFormat The server’s input format type. This can be retrieved from the session object’s

inputFormat property.

pKeyType

pValueType

ActionScript objects act as associative arrays (similar to java Maps), the

convertObjectToMultivalue() method takes a key type and value type.

These arguments are similar to pComponentType and are absolute names of Java

classes to use for the key and value objects in the Java Map.

Similar to the Java client library, passing arguments to methods is generally straightforward. For primitive types,

just add them to the pArguments array.

402 8 Legacy Rest Client Libraries

var result:RestResult = RestComponentHelper.executeMethod("/some/Component","aMethod", [1,2,3,4.4,5.5,true,'a',0xa], null, session, handleResult, handleFault)

To pass a reference to a repository item, use the format

<repository path:item descriptor name:item id>

For example:

var result:RestResultRestComponentHelper.executeMethod("/some/Component","aMethod", ["/atg/commerce/catalog/ProductCatalog:product:prod12345"], null,session, handleResult, handleFault)

To pass a reference to a Nucleus component, pass the Nucleus component path. For example:

var result:RestResultRestComponentHelper.executeMethod("/some/Component","aMethod", ["/atg/dynamo/Configuration"], null, session, handleResult,handleFault)

The following example is a call to a method which takes a repository item array and a GenericService array.

<programlisting>var result:RestResultRestComponentHelper.executeMethod("/some/Component","aMethod",[["/atg/commerce/catalog/ProductCatalog:product:prod12345","/atg/commerce/catalog/ProductCatalog:product:prod67890"],["/atg/dynamo/Configuration","/atg/dynamo/Configuration"]], null, session, handleResult, handleFault)

As mentioned above, arrays, ILists, and Objects must be converted before being passed to the server. The

following example demonstrate passing an array using the helper methods in the RestClientUtils class.

var arrayCollection:ArrayCollection = new ArrayCollection(["abc","def"]);var result:RestResultRestComponentHelper.executeMethod("/some/Component","aMethod", [RestClientUtils.convertIListToMultivalue(arrayCollection,"java.util.ArrayList", "java.lang.String", RestConstants.JSON, session)], null, session, handleResult, handleFault);

The following example, which calls executeMethod(), produces the same result as the previous example:

var result:RestResultRestComponentHelper.executeMethod("/some/Component","aMethod", ["java.util.ArrayList:java.lang.String:[\"abc\",\"def\"]"], null,session, handleResult, handleFault)

The following examples use the helper methods in the RestClientUtils class.

var result:RestResultRestComponentHelper.executeMethod("/some/Component","aMethod", [RestClientUtils.convertArrayToMultivalue(["abc","def"],

8 Legacy Rest Client Libraries 403

"java.util.HashSet", "java.lang.String", RestConstants.JSON, session)], null, session, handleResult, handleFault)

var obj:Object = new Object();obj["abc"] = 123;obj["def"] = 456;

var result:RestResultRestComponentHelper.executeMethod("/some/Component","aMethod", [RestClientUtils.convertObjectToMultivalue(obj, "java.util.HashMap","java.lang.String", "java.lang.Integer", RestConstants.JSON, session)], null, session, handleResult, handleFault)

Formatting Input with ActionScript

The option to use JSON or XML with ActionScript is available. In order to use JSON you will need to include the

Adobe corelib library. This library contains functionality to encode and decode JSON streams. In the example

below, the pEvent object is of type Event and is supplied by the Flash runtime when the handler method is

called. pEvent.target.data contains the response data stream. This stream is decoded into an Object. The

sample iterates through the properties constructing an object for each name/value pair and then adds it to an

ArrayCollection object.

var json:Object = JSON.decode(pEvent.target.data);for (var propName:String in json) arrayCollection.addItem({name: propName, value: json[propName]});

The following sample uses XML input. Note that you could also take advantage of the ECMAScript for XML

functionality once the XML object is created. The following sample does not use that approach, though it is an

option.

var xml:XML = new XML(pEvent.target.data);var xmlList:XMLList = pXML.elements();if (xmlList.length() == 0) xmlList = new XMLList(pXML); var count:int = 0;for each(var item:XML in xmlList) { if (item.name() != "element") array.addItem({name: item.name(), value: item.text()}); else if (item.hasComplexContent()) { var elementList:XMLList = item.child("element"); if (elementList != null &amp;&amp; elementList.length() > 0) { var count2:int = 0; for each (var el:XML in elementList) array.addItem({name: count2++, value: el.text()}); } else array.addItem({name: item.key.text(), value: item.value.text()}); } else array.addItem({name: count++, value: item.text()});}

404 8 Legacy Rest Client Libraries

Index 405

Index

AActivateScheduleActor, 258

ActiveCustomerProfileActor, 239

Actor

ActivateScheduleActor, Internal, 258

ActiveCustomerProfileActor, Internal, 239

AddressBookActor, Internal, 209

AddStoreCreditActor, Internal, 280

AvailablePricedShippingMethodsActor, Internal, 228

AvailableShippingMethodsActor, External, 133

CancelOrderActor, External, 151

CancelOrderActor, Internal, 244

CartModifierActor, External, 124

CartModifierActor, Internal, 218

ChangeCurrentCustomer, Internal, 208

ChangeOrderActor, Internal, 243

ChangePasswordActor, Internal, 182

ChangeSiteActor, Internal, 314

ClosenessQualifierActor, External, 156

ClosenessQualifierActor, Internal, 278

CommitOrderActor, External, 156

CommitOrderActor, Internal, 246

ConfirmLogoutActor, Internal, 182

ConfirmOrderActor, External, 152

ConfirmOrderActor, Internal, 247

CouponActor, External, 152

CouponActor, Internal, 234

CreateCreditCardActor, External, 141

CreateCreditCardActor, Internal, 235

CreateHardgoodShippingGroupActor, External, 133

CreateHardgoodShippingGroupActor, Internal, 228

CreditCardActor, Internal, 212

CSRCrossSellActor, Internal, 245

CSRGiftlistActor, Internal, 281

CSRGiftlistSearchActor, Internal, 288

CSRReturnsActor, Internal, 294

CSRScheduledOrderActor, Internal, 253

CSRScheduledOrderConfirmationActor, Internal, 260

CSRScheduledOrderInfoActor, Internal, 259

CustomerProfileActor, Internal, 203

CustomerSearchTreeQueryActor, Internal, 206

DeactivateScheduleActor, Internal, 258

DefaultLoginPageActor, Internal, 183

DuplicateAndSubmitActor, Internal, 257

DuplicateOrderActor, Internal, 251

EndCallActor, Internal, 184

EnvironmentChangeActor, Internal, 270

GiftlistActor, External, 166

GiftlistLookupActor, External, 171

GiftlistLookupActor, Internal, 287

GiftlistSearchActor, External, 174

GiftListTableActor, Internal, 290

GlobalInfoActor, Internal, 313

IsScheduledOrderTemplateActor, Internal, 262

LostPromotionsActor, External, 165

LostPromotionsActor, Internal, 280

ManualAdjustmentsActor, Internal, 265

MessageToolsActor, Internal, 315

ModifyOrderActor, Internal, 250

ModifyRefundValuesActor, Internal, 308

MoreCatalogsSearchActor, Internal, 269

OrderConfirmationActor, External, 156

OrderConfirmationActor, Internal, 249

OrderLookupActor, External, 150

OrderNoteActor, Internal, 251

OrderSearchTreeQueryActor, Internal, 241

OriginalOrderNoteActor, Internal, 252

PaymentGroupActor, External, 135

PaymentGroupActor, Internal, 230

PriceListSearchActor, Internal, 274

PricingActor, External, 148

PricingActor, Internal, 271

ProductCatalogActor, External, 143

ProductCatalogActor, Internal, 267

ProfileActor, External, 116

PromotionsSearchActor, Internal, 279

PromotionWalletActor, Internal, 274

QuoteActor, Internal, 252

RespondEmailActor, Internal, 310

RestoreDefaultAgentOptionsActor, Internal, 183

ReturnsActor, External, 157

SaveOrderActor, External, 152

ScheduledOrderLookupActor, Internal, 262

ScheduledOrderTableActor, Internal, 264

SendAndCloseTicketActor, Internal, 311

ServiceCustomerProfileActor, Internal, 239, 288

ServiceUIProfileActor, Internal, 202

SessionConfirmationActor, External, 116

SessionConfirmationActor, Internal, 180

ShippingGroupActor, External, 129

ShippingGroupActor, Internal, 224

ShoppingCartActor, External, 121

ShoppingCartActor, Internal, 215

SiteGroupsActor, Internal, 314

406 Index

StartNewCallActor, Internal, 183

StateListActor, External, 177

StoreLocatorActor, External, 176

StoreLocatorActor, Internal, 291

SubmitModifiedOrderActor, Internal, 250

TicketActor, Internal, 186

TicketingActor, Internal, 185

TicketLookupActor, Internal, 196

TicketSearchActor, Internal, 200

TicketStatusDescriptionActor, Internal, 202

UpdateCreditCardActor, External, 142, 164

UpdateCreditCardActor, Internal, 237, 304

UpdateHardgoodShippingGroupActor, External, 134

UpdateHardgoodShippingGroupActor, Internal, 229

ViewAllPendingApprovalsActor, Internal, 291

ViewOrderActor, Internal, 243

actor-chains, 71

registering, 69

actors, 71

execution order, 94

passing params, 83

types, 72

AddressBookActor, 209

AddStoreCreditActor, 280

Apache Axis, 35

ATGWS.dll, 45

installing, 46

AvailablePricedShippingMethodsActor

Internal, 228

AvailableShippingMethodsActor

External, 133

CCancelOrderActor

External, 151

Internal, 244

CartModifierActor

External, 124

Internal, 218

ChangeCurrentCustomerActor, 208

ChangeOrderActor, 243

ChangePasswordActor, 182

ChangeSiteActor, 314

ClosenessQualifierActor

External, 156

Internal, 278

CommitOrderActor

External, 156

Internal, 246

ConfirmLogoutActor, 182

ConfirmOrderActor

External, 152

Internal, 247

CouponActor

External, 152

Internal, 234

CreateCreditCardActor

External, 141

Internal, 235

CreateHardgoodShippingGroupActor

External, 133

Internal, 228

CreditCardActor, 212

CSRCrossSellActor, 245

CSRGiftlistActor, 281

CSRGiftlistSearchActor, 288

CSRReturnsActor, 294

CSRScheduledOrderActor, 253

CSRScheduledOrderConfirmationActor, 260

CSRScheduledOrderInfoActor, 259

cURL, 59

command components, 61

CustomerProfileActor, 203

CustomerSearchTreeQueryActor, 206

DDeactivateScheduleActor, 258

DefaultLoginPageActor, 183

DuplicateAndSubmitActor , 257

DuplicateOrderActor, 251

dynSessConf, 70, 81, 87

EEndCallActor, 184

EnvironmentChangeActor, 270

Ffilters

bean classes, in REST MVC, 101

defining in REST MVC, 102

Legacy REST, 366

modifying in REST MVC, 109

repository items, in REST MVC, 101

GGiftlistActor, 166

GiftlistLookupActor

External, 171

Internal, 287

GiftlistSearchActor, 174

GiftListTableActor, 290

GlobalInfoActor, 313

HHTTP

Index 407

requests, 57, 61

requests in Legacy REST, 321, 335

status codes, 57, 345

IIsScheduledOrderTemplateActor, 262

JJAX-RPC, 4, 9, 11

and WSDL, 8

JMS Messages, 16

Patch Bay, 16

type, 16

JSON

output in Legacy REST, 335

output in MVC REST, 58

LLostPromotionsActor

External, 165

Internal, 280

MManualAdjustmentsActor, 265

message sink, 18

MessageToolsActor, 315

methods

executing with Legacy REST, 321

executing with REST MVC, 77

overloaded, specifying in REST MVC, 80

ModelMap, 71, 73

and filtering, 101

and hierarchy, 76, 99

and output elements, 92

ModifyOrderActor, 250

ModifyRefundValuesActor, 308

MoreCatalogsSearchActor, 269

OOrderConfirmationActor

External, 156

Internal, 249

OrderLookupActor, 150

OrderNoteActor, 251

OrderSearchTreeQueryActor, 241

OriginalOrderNoteActor, 252

PPatch Bay, 15, 17

PaymentGroupActor

External, 135

Internal, 230

PriceListSearchActor, 274

PricingActor

External, 148

Internal, 271

ProductCatalogActor

External, 143

Internal, 267

ProfileActor, 116

PromotionsSearchActor, 279

PromotionWalletActor, 274

pushSite, 116

QQuoteActor, 252

Rrepository

data binding Web Services, 21

delete item, 34

filtering in REST MVC, 109

items from XML, 29

items in Legacy REST, 358

match properties, 33

modify item, 32

RespondEmailActor, 310

REST, 55

cURL examples, 59

HTTP status codes, 57

output, 58

URLs, 56

URLs, adding parameters, 64

REST Legacy, 321

cURL example, 60

filtering, 366

framework, 56, 319

HTTP requests, 321

HTTP status codes, 345

output, default, 335

output, JSON, 336

output, XML, 336

repositories and, 358

security, 379

URLs, 321

URLs, adding parameters, 327

REST MVC, 67

cURL example, 60

examples, external user, 115

examples, internal users, 179

executing methods, 77

filtering, 101

framework, 56, 71

installing, 69

registering services, 69

408 Index

schema, 73

security, 110

URLs, 73

URLS, error and success, 86

RestoreDefaultAgentOptionsActor, 183

ReturnsActor, 157

SSaveOrderActor, 152

Scenario Actions, 16

Scenario Manager, 18

ScheduledOrderLookupActor, 262

ScheduledOrderTableActor, 264

security

Legacy REST, 379

REST MVC, 110

Web Services, 12

SendAndCloseTicketActor, 311

Service Endpoint Interface (SEI), 8

mapping to WSDL, 11

ServiceCustomerProfileActor, 239, 288

ServiceUIProfileActor, 202

servlet beans

filtering in REST MVC, 103

in Legacy REST, 357

retrieving in REST MVC, 84

session confirmation number, 70, 116, 180

disabing in Form actors, 87

disabling in Component actor, 81

SessionConfirmationActor

External, 116

Internal, 180

ShippingGroupActor

External, 129

Internal, 224

ShoppingCartActor

External, 121

Internal, 215

site context, external, 116

SiteGroupsActor, 314

SOAP, 4, 8, 9

and WSDL, 8

StartNewCallActor, 183

StateListActor, 177

StoreLocatorActor

External, 176

Internal, 291

SubmitModifiedOrderActor, 250

TTicketActor, 186

TicketingActor, 185

TicketLookupActor, 196

TicketSearchActor, 200

TicketStatusDescriptionActor, 202

UUpdateCreditCardActor

External, 142, 164

Internal, 237, 304

UpdateHardgoodShippingGroupActor

External, 134

Internal, 229

URLs, 56

adding Legacy REST parameters, 327

adding REST parameters, 64

and WSDL, 9

control parameters, 62

forwarding in REST MVC, 86

Legacy REST, 321

REST MVC, 73

success and error in REST MVC, 86

VViewAllPendingApprovalsActor, 291

ViewOrderActor, 243

WWeb Services

.Net, 44, 47

abstract data types, 5

cookies, 5, 37

DAS, 2

DCS, 2

deploying, 13

deserializer in .Net, 45, 49

deserializer in Java, 36, 42

DPS, 2

dynamic, 39, 41

exposing methods, 8

Java client, 35

JMS Messages, 15

JMS Type, 16

naming conflict, 5, 7

NucleusSecurityManager, 12

NucleusSecurityRepository, 13

primitive data types, 5, 8

Registry, 8, 11, 14

repository, for, 18

rollback a call, 35

scenario actions, 16

security, 4, 12

serializer in .Net, 45, 49

serializer in Java, 36, 42

session sharing, 36, 45

static, 39, 39

Index 409

wizard, 5

WSDL, 8, 10

XML file, 9

Web Services Description Language (WSDL) (see Also Web

Services)

mapping to SEI, 11

WebServicesGenerator, 6

XXML

data binding, 21

data binding in REST MVC, 100

delete repository item, 34

generating schemas, 43

mapping in Web Services, 22

mapping Web Services DTD, 23

output in Legacy REST, 336

output, REST, 58

repository items, 29

schema mapping, 42

schemas, 27

validating, 32

410 Index