Version 11.

Web Services Guide

Oracle ATG
One Main Street
Cambridge, MA 02142
USA

Web Services Guide

Product version: 11.1
Release date: 06-27-14
Document identifier: WebServicesGuide1502251324
Copyright 1997, 2014 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 on 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. 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.
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 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.

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

Web Services Guide

iii

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Actor XML Definition File Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Working with Implicit Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Combining Actor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Bean Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
The Bean Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
The Filter Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
The Property Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
The Attribute Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
The Repository Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
The Item-Descriptor Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Working with Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Configuring REST MVC Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
REST MVC Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Example: External User Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Example: Internal User Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
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

iv

Web Services Guide

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

Removing and Adding an Item to the Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing an Item From the Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing an Item From the Shopping Cart By Relationship ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Checkout Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with the Shipping Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying the Default Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying the Default Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining the Current Shipping Info List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Shipping Groups and Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Splitting Commerce Items into Different Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Available Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Hardgood Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing a Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Display the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying the Default Payment Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Default Payment Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Current Payment Info Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Multiple Payment Groups to an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Credit Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a Credit Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting the Users Current Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Browsing the Catalog By Category ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Browsing the Catalog By Product ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching a Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Product Prices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Lowest and Highest Prices for a Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting List Price and Sale Prices for a Product by SKU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Looking Up an Order by Order ID or User ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cancelling or Deleting an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Claiming a Coupon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Confirming an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Committing an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Order Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Closeness Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Returns and Exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initiating a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting Items to Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Return Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Confirming a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Return Confirmation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Canceling a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning Refund Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Non-Default Refund Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying Returnable Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Details of Returned Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reviewing Return History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Showing Non-Return Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Web Services Guide

127
128
128
128
129
129
129
131
131
131
132
132
133
133
134
135
135
136
137
137
140
140
141
142
143
143
145
146
146
146
147
147
148
149
149
150
150
153
154
154
155
155
156
158
159
159
159
160
160
161
161
161
162

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

Updating Credit Cards for a Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Lost Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Gift Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Items to a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Items to a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing Items from a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing Items from a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Moving Items to a Gift or Wish List from a Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing the Current Profiles List of Gift Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Gift Lists Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with In-Store Pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for a Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Search Results for In-Store Pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying a State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6. Internal REST MVC Service Call Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Internal REST MVC Service Calls Workflow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting the Session Confirmation Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Agents In and Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging In Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Out Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Confirming Log Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing Agents Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Default Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restoring Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ending a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Call Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Tickets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Ticket to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Associating a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Escalating a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Releasing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deferring a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reassigning a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending a Ticket to a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing a Ticket as Duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
End Editing a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Active Tickets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Looking Up a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for a Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reviewing a Ticket Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vi

162
162
163
164
164
165
165
166
166
167
167
168
168
169
169
171
172
174
174
175
175
177
177
178
179
179
179
180
180
181
181
181
181
182
183
184
185
185
186
186
187
188
188
189
190
190
191
191
192
193
194
198
200

Web Services Guide

Viewing a Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Customer Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating an Existing Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Note to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Clearing a Customer Search Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Customer to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Customer Profile Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding an Address to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing an Address in a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting an Address from a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Credit Cards Within a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Credit Card to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing a Credit Card in a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Credit Card from a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Multiple Items to a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Items to a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating the Customers Shopping Cart by SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating the Customers Shopping Cart by Commerce ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating the Customers Shopping Cart By Shipping Group Relationship ID . . . . . . . . . . . . . . . .
Removing and Adding an Item to the Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing an Item From the Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing an Item From a Customers Shopping Cart By Relationship ID . . . . . . . . . . . . . . . . . . . .
Starting the Checkout Process with SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Checkout Process with Commerce ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Checkout Process with Relationship ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the SKU of an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting the Customer with the Shipping Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Available Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying a Single Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Multiple Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Splitting Items into Different Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying All Available Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating New Hardgood Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing a Hardgood Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining the Customers Current Shipping Info List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting the Customer with the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Display the Customers Payment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Available Payment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Claiming Store Credit or a Gift Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Claiming a Customers Coupon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Multiple Payment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Credit Cards Within an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting a Customers Existing Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Credit Card to an Existing Address in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Credit Card to a New Address in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a Credit Card in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting Customers with Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating New Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Web Services Guide

200
201
201
203
204
204
206
206
207
208
209
209
210
210
211
213
213
216
217
218
219
219
220
220
220
221
221
221
222
222
222
223
223
224
224
225
226
226
227
228
228
229
229
231
232
232
233
233
233
234
235
236
236

vii

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

Viewing the Customer Order History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching and Clearing Searches for an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Finding an Order by Order ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting an Order to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cancelling or Deleting the Current Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Cross Sell Items in a Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving or Committing an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Confirming a Customers Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending a Customer Order Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying a Submitted Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Submitting a Modified Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Duplicating an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Note to a Customers Current Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Note to a Customers Original Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Quote for a Customers Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Scheduled Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Submitting a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Activating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deactivating a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Scheduled Order Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Scheduled Order Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Scheduled Order Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Template from a Scheduled Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Validating a Scheduled Order Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending E-Mail Confirmation for a Scheduled Order Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying a Template Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reviewing a Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Template Order List of Submitted Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Users List of Template Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adjusting Customers Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adjusting a Customers Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting an Adjustment from a Customers Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overriding an Items Price in the Customers Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting Customers with Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting the Customers Current Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Browsing the Customers Catalog By Category ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Browsing the Customers Catalog By Product ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Search a Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for Catalogs with Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with the Current Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Product Prices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Price Ranges for a Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining List Price and Sale Prices for a Product by SKU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Customers Price Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Current Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving the Current Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Resetting the Current Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for a Price List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Customers Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Available Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

viii

237
237
239
241
241
242
243
244
245
247
248
248
249
249
250
250
251
251
254
255
256
256
257
258
258
259
259
260
260
260
261
262
263
263
264
264
265
265
266
266
267
267
268
269
269
270
270
270
271
271
271
272
273

Web Services Guide

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

Adding a Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing a Promotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Include Promotions from Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ignoring Promotions from Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving the Promotions Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reverting the Promotions Wallet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Closeness Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Store Credit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Lost Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Changed Promotions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Customers Gift Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Customers Gift or Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a Customers Gift or Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Items to a Customers Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Items to a Customers Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing Items from a Customers Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing Items from a Customers Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Moving Items to a Gift or Wish List from a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Customers Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Customers Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Customers Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for a Customers Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a List of Customers Gift or Wish Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting Customers with In-Store Pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Finding Pending Approvals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Approving or Rejecting a Pending Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting the Customer with Returns and Exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returns and Exchange Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Items to a Return Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Return Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Confirming a Return Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Return Request Confirmation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cancelling a Return Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Return Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving Available Refund Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Refunds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Return History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying if the Order is Returnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying if an Item is Returnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying if the Order Contains an Active Return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reviewing Details of Returned Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Non-Return Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a Credit Card for a Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying Refund Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modify a Refund Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Resetting a Refund Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Responding to Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending a Customer E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding an Attachment to an E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Web Services Guide

274
274
274
275
275
275
276
276
276
277
278
278
279
279
281
282
283
283
283
284
284
285
286
286
288
289
289
289
290
291
291
293
294
297
297
297
298
298
298
299
299
300
300
300
301
302
302
303
303
304
304
305
305

ix

Discarding an E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Customer E-Mail and Closing Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with the Commerce Service Center Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Global Session Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Listing Available Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Ticket Disposition Warnings and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
II. Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7. Using Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HTTP Requests for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Nucleus Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling POST Requests as Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging In as an External User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging In as an Internal User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functional Parameters for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input Values in Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returned Data in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Choosing Output Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSON Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Values in Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Date Format in Returned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Errors and Exceptions in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Problems Performing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Problems Processing a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Legacy REST Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Legacy REST Component Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Legacy REST Form Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Submitting Legacy REST Form Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning Legacy REST Form Handler Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning Legacy REST Form Handler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Legacy REST Form Value Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Java Server Pages (JSPs) with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Legacy REST Web Services JSP Configuration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
URL Templates for Legacy REST Web Services JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Legacy REST Service Processor Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example Legacy REST Web Services JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Repositories in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Listing Repository Items in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving a Specific Property Using Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performing RQL Queries in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

306
306
307
307
308
309
310
311
315
317
317
317
317
318
318
319
319
320
322
323
323
325
331
331
332
332
333
334
339
340
341
341
342
343
343
344
345
346
347
348
348
349
350
351
351
352
353
354
354
355
356
357
358

Web Services Guide

Transient Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Repository Item Properties in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Property Filtering with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Filtering in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering Templates with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering for One Request with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Property Aliasing with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suppressing Property Expansion in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering Priority in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Legacy REST Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/processor/BeanProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/output/JSONOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/output/XMLOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/processor/RepositoryProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/processor/RestSecurityProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security for Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Legacy REST Security Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Quick Setup for Testing Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Global Security with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Component Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Property and Method Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Repository Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Securing Groups of Components in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8. Legacy Rest Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a RestSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting a REST Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging in and Logging Out with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting a Session Without Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Data from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Raw REST Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Components with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Methods with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Repository Items with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Java Client in Android Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ActionScript Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atg.rest.client.RestComponentHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atg.rest.client.RestRepositoryHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Methods with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting Input with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Web Services Guide

360
360
361
362
362
365
366
367
368
369
369
370
370
371
372
374
375
375
375
376
377
377
377
378
378
381
381
381
383
384
385
386
387
388
389
390
390
392
395
395
396
396
397
399
401

xi

xii

Web Services Guide

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 employees profile in both systems.
Ideally, youd 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 employees 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 youre 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)

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

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

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 Oracles 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

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 Microsofts .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 methods class is your own custom code), or else subclass the
methods 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

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

 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

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 platformindependent way. A WSDL document describes a Web Services 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 Services 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

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

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=GetOrderStatusSEIService
port0.tie=webservices.GetOrderStatusSEI_Tie
wsdl.transform=true
port0.name=getOrderStatus
portcount=1
wsdl.location=WEB-INF/getOrderStatus.wsdl
port0.servant=webservices.GetOrderStatusSEIImpl
port0.wsdl.targetNamespace=http\://www.atg.com/webservices
port0.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>

10

1 Creating and Using Web Services

<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

1 Creating and Using Web Services

11

 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 services security
configuration, the name of the Nucleus component and method exposed by the service, and a Map containing
the methods 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).

12

1 Creating and Using Web Services

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:

1 Creating and Using Web Services

13

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 applications
name. For example, if you click on the link for the Pricing application, the Service Info looks like this:

14

1 Creating and Using Web Services

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

1 Creating and Using Web Services

15

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 messages 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
clients 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);

16

1 Creating and Using Web Services

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>

1 Creating and Using Web Services

17

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

18

1 Creating and Using Web Services

 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

1 Creating and Using Web Services

19

 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

20

1 Creating and Using Web Services

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

1 Creating and Using Web Services

21

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.

22

1 Creating and Using Web Services

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 in
another datamodel. A given mapping file gives the ability to
control what properties are included/excluded from the datamodel
control how names in one model relate to names in another model
-->
<!-Defines the mapping for a given item-descriptor. The name and repository
property are required properties. The name property corresponds to the
name of a given item-descriptor. The repository should be the Nucleus
path to a particular repository. For example, if an item-descriptor mapping
was going to point to the the ProfileAdapterRepository located at
/atg/userprofiling/ProfileAdapterRepository Nucleus path, then the repository
property should be the string "/atg/userprofiling/ProfileAdapterRepository".
The default-include exists to indicate whether or not properties that are
associated with this item-descriptor should be included by default or not.
This property defaults to true. So, if a property is does not explicitly
appear as a child property element, it is assumed to be included in the
data 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 given
mapping; whether the property should be included or not and what the
targetName for the target datamodel should be. The name attribute corresponds
to the name of a property defined for a given item-descriptor. The include
attribute is optional. If it is not specified, the value is obtained from the
default-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"

1 Creating and Using Web Services

23

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 items 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
<property
<property
<property

name="slotInstances" include="false"/>
name="scenarioInstances" include="false"/>
name="mailings" include="false"/>
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:

24

1 Creating and Using Web Services

<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.ItemDescriptorMapping
atg.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.ItemDescriptorMapping
repository=/atg/userprofiling/ProfileAdapterRepository
itemDescriptorMapping=\
user=/atg/userprofiling/userMapping.xml,\
contactInfo=/atg/userprofiling/contactInfoMapping.xml

1 Creating and Using Web Services

25

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.ItemDescriptorMappingManager
itemDescriptorMappings=\
/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.

26

1 Creating and Using Web Services

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):

1 Creating and Using Web Services

27

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 Managers
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:

28

1 Creating and Using Web Services

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

1 Creating and Using Web Services

29

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 Quincy
Funds 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>

30

1 Creating and Using Web Services

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

1 Creating and Using Web Services

31

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 users 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>

32

1 Creating and Using Web Services

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

1 Creating and Using Web Services

33

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.

34

1 Creating and Using Web Services

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, its 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.

1 Creating and Using Web Services

35

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

36

1 Creating and Using Web Services

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
import
import
import

org.apache.axis.MessageContext;
org.apache.axis.client.Call;
org.apache.axis.client.Stub;
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

1 Creating and Using Web Services

37

**/
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);

38

1 Creating and Using Web Services

}
}

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 its primitive, complex, object, or nonstandard. 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.

1 Creating and Using Web Services

39

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 thats 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
Its 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();

40

1 Creating and Using Web Services

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/class
CookieContainer cookieContainer = new CookieContainer();
// Push previous cookies (if any) to the new Call object
cookieContainer.pushCookies(call);
call.setMaintainSession(true);
call.setTargetEndpointAddress(new
java.net.URL("http://hostname:port/userprofiling/usersession/loginUser/
loginUser") );
// Don't allow XML elements to reference other XML elements
call.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"));

1 Creating and Using Web Services

41

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 calls
cookieContainer.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).

42

1 Creating and Using Web Services

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 Repositorys 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 applications 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, its 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:

1 Creating and Using Web Services

43

 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 thats 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, its 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.

44

1 Creating and Using Web Services

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)

1 Creating and Using Web Services

45

 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-unknownwin32/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-unknownwin32/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. Theres 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 youd 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-

46

1 Creating and Using Web Services

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.

1 Creating and Using Web Services

47

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
using
using
using
using

System.Net; // for CookieContainer

Atg.DotNet.WebService.Repository.GetItem;
Atg.DotNet.WebService.Repository.PerformRQLQuery;
Atg.DotNet.WebService.UserSession.LoginUser;
Atg.DotNet.WebService.UserSession.LogoutUser;

// create stub instances

GetItemSEIService getItemClientStub = new GetItemSEIService();
PerformRQLQuerySEIService performRQLQueryClientStub = new
PerformRQLQuerySEIService();
LoginUserSEIService loginUserClientStub = new LoginUserSEIService();
LogoutUserSEIService logoutUserClientStub = new LogoutUserSEIService();
// create a new cookie container for our session and share it between
// the various stub instances
CookieContainer cookieContainer = new CookieContainer();
getItemClientStub.CookieContainer = cookieContainer;
performRQLQueryClientStub.CookieContainer = cookieContainer;
loginUserClientStub.CookieContainer = cookieContainer;
logoutUserClientStub.CookieContainer = cookieContainer;
// authenticate the user for the session
loginUserClientStub.loginUser("user", "password", false);
// call services
string itemXml =
getItemClientStub.getItem("/nucleus/path/to/repository",
"itemDescriptorName", "repositoryId");
string[] itemsXml =
performRQLQueryClientStub.performRQLQuery("/nucleus/path/to/repository",
"itemDescriptorName", "property = 'value'");

48

1 Creating and Using Web Services

// log out the user

logoutUserClientStub.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, theres 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 objects clean/dirty status

1 Creating and Using Web Services

49

 Use the RepositoryItem.setPropertyDirty() methods to toggle a propertys 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 propertys 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 objects RepositoryItem.

Properties

List of properties for this RepositoryItem.

RepositoryId

ID provided to the objects RepositoryItem representation.

RepositoryName

Name of the repository that the RepositoryItem is part of.

50

1 Creating and Using Web Services

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, its 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 propertys 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 propertys name and value.

1 Creating and Using Web Services

51

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

52

1 Creating and Using Web Services

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.

1 Creating and Using Web Services

53

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.

54

1 Creating and Using Web Services

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 315) 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.

2 Introduction to REST Web Services

55

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 317) 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

56

2 Introduction to REST Web Services

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.

2 Introduction to REST Web Services

57

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
331) section.

58

2 Introduction to REST Web Services

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 commandline 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/

2 Introduction to REST Web Services

59

<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",

60

2 Introduction to REST Web Services

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 commandline 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 agentbased 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 atgrest-user-input control parameter to specify that identifying string.

2 Introduction to REST Web Services

61

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-multivalues

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-classdescriptor

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 atgrest-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-tagpriorities

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.

62

2 Introduction to REST Web Services

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-classtypes

Both Legacy
and MVC

Use this parameter to specify the Java classes for

multiple values in JSON functional parameters. The atgrest-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-restparam-class-types as shown below.
{'container-class':
'java.util.ArrayList',
'element-class':'java.lang.String'}

Use the key-class attribute when the containerclass implements java.util.Map. For example:
{'container-class':'java.util.HashMap',
'key-class':'java.lang.String',
'element-class':'java.lang.String'}
atg-rest-propertyfilters

Legacy Only

Use this parameter to apply property filtering to individual

Legacy REST Web Services Requests.

atg-rest-propertyfilter-templates

Legacy Only

Use this parameter to apply property filter templates to

individual REST Web Services Requests.

2 Introduction to REST Web Services

63

Parameter

REST Version

Explanation

atg-rest-return-formhandler-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-formhandler-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-simpleresponse-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.

64

2 Introduction to REST Web Services

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 318).

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.

2 Introduction to REST Web Services

65

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.

66

Array Type

Java Notation

String

[Ljava.lang.String;

byte

[B

int

[I

Two-dimensional array of Strings

[[Ljava.lang.String;

2 Introduction to REST Web Services

Part I. Oracle Commerce

Platform REST MVC Web Services
The 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 177) 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

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

3 Installing and Configuring the REST MVC Server

69

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.

70

3 Installing and Configuring the REST MVC Server

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

4 The REST MVC Definition Framework

71

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 actorchain.
The REST Service also verifies the users access using the AccessControllerService.
2. The REST Service initializes the actor context from the REST control parameters and the URL. The actorcontext 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 APIs 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

72

4 The REST MVC Definition Framework

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 177) 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.

4 The REST MVC Definition Framework

73

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:

74

4 The REST MVC Definition Framework

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

4 The REST MVC Definition Framework

75

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-ifpresent

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 actors input. Actors can have multiple input elements.

output

This element defines each actors 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 98) 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>

76

4 The REST MVC Definition Framework

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 components properties.

method-return-var

Identifies the variable name that accesses the method invocations returned
value.

set-propertyrequires-sessionconfirmation

By default, all set-property values require session confirmation numbers. This

property is set to true by default.

invoke-methodrequires-sessionconfirmation

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 actors input. Actors can have multiple input
elements.

output

This element defines each actors 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}"/ >

4 The REST MVC Definition Framework

77

</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"

78

4 The REST MVC Definition Framework

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"

4 The REST MVC Definition Framework

79

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

80

4 The REST MVC Definition Framework

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.

4 The REST MVC Definition Framework

81

Attribute/Element

Description

depends-ifpresent

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 actors input. Actors can have multiple input elements.

output

This element defines each actors 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">

82

4 The REST MVC Definition Framework

<!-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"/>

4 The REST MVC Definition Framework

83

<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 95) 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:

84

Attribute/Element

Description

name

Required. This is the Nucleus path of the form handler.

4 The REST MVC Definition Framework

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-sessionconfirmation

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-ifpresent elements associated with an actor.

input

This element defines each actors input. Actors can have multiple input
elements.

output

This element defines each actors 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/
purchase/CartModifierActor/addItemToOrder-success"/>
</form>
</actor-chain>

4 The REST MVC Definition Framework

85

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

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:

86

4 The REST MVC Definition Framework

<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:

<actor-chain id="login" transaction="TX_SUPPORTS">

4 The REST MVC Definition Framework

87

<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}" />
</actor>
</actor-chain>

88

4 The REST MVC Definition Framework

<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 and

login 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.
The jsp element contains the following:

4 The REST MVC Definition Framework

89

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-ifpresent

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 actors input. Actors can have multiple input elements.

output

This element defines each actors 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" />
<dsp:importbean bean="/atg/commerce/order/purchase/ShippingGroupFormHandler" />
<dsp:importbean bean="/atg/commerce/ShoppingCart" />
<dsp:importbean bean="/atg/userprofiling/Profile" />

90

4 The REST MVC Definition Framework

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

Example: Migrating Previous REST JSP Templates

To apply Oracle Commerce Platform Legacy REST JSP templates to the JSPActors:

4 The REST MVC Definition Framework

91

<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:

92

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 98) 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 98) 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.

message

The output tag supports internationalized messages that are added to the
ModelMap.

4 The REST MVC Definition Framework

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 users 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 users 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:

{"error": {
"messageCode" : "PRODUCT_NOT_IN_CURRENT_CATALOG",
"localizedMessage" : "Product xprod2099 is not defined in the current catalog"
}}

4 The REST MVC Definition Framework

93

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 methods parameters. Refer to The Component Element (page 77)
section for additional information on this attribute.

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

94

4 The REST MVC Definition Framework

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>

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.

4 The REST MVC Definition Framework

95

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.

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

96

4 The REST MVC Definition Framework

$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 actortemplate 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>
<!-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">

4 The REST MVC Definition Framework

97

<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">
...
</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:

98

4 The REST MVC Definition Framework

Object

Description

atgActorModel

Maps the current actor-chains modelMap. This does not reference the parent
chains 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 users session.

Accessing Actor Context Variables

Actor context variables and attributes are available only for the duration of the actor-chain. Each nested actorchain or child actor-chain is given a new ActorContext and ModelMap, and is unable to reference their parents
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
98) 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.
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:

4 The REST MVC Definition Framework

99

<!-- 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 Page Developer's Guide.

100

Element

Match Attribute

actor

id

actor-chain

id

component

id

depends

id

depends-if-present

id

droplet

id

form

id

input

name

4 The REST MVC Definition Framework

Element

Match Attribute

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"
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">

4 The REST MVC Definition Framework

101

<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 afilter 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:
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>

102

4 The REST MVC Definition Framework

</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>
<!-<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:

4 The REST MVC Definition Framework

103

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">
<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

104

4 The REST MVC Definition Framework

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

4 The REST MVC Definition Framework

105

Attribute

Description

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.

propertycustomizer

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:
<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>

106

4 The REST MVC Definition Framework

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 105) 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.

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.

4 The REST MVC Definition Framework

107

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">
<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:

108

4 The REST MVC Definition Framework

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

4 The REST MVC Definition Framework

109

Property

Description

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

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=

110

4 The REST MVC Definition Framework

/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.RuleAccessController
enabled=true
# Rules used to determine whether access should be allowed
ruleSetService=/atg/rest/targeting/LoggedInRuleSetService
# URL to redirect to if access is denied
deniedAccessURL=/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:
/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"?>

4 The REST MVC Definition Framework

111

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

112

4 The REST MVC Definition Framework

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"/>
<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/

4 The REST MVC Definition Framework

113

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 report
message - Your session expired due to inactivity.
description - The request could not be completed due to a conflict with the
current state of the resource.

114

4 The REST MVC Definition Framework

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 177) 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 customers 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.

5 External REST MVC Service Call Examples

115

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 environments 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:

116

5 External REST MVC Service Call Examples

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 customers 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 customers 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 and
login do not match","errorCode":"invalidPassword"}]}

Logging Out Customers

The logout actor-chain is used to log the customer out of the application.

5 External REST MVC Service Call Examples

117

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.

118

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 customers e-mail address.

password

The customers password.

confirmPassword

Re-enter the customers password to verify.

login

The customers log in name.

dateOfBirth

The customers date of birth.

gender

The customers gender.

homeAddress.address1

The first address line of the customers home address.

homeAddress.address2

The second address line of the customers home address.

homeAddress.address3

The third address line of the customers home address.

homeAddress.city

The city associated with the customers home address.

homeAddress.state

The state associated with the customers home address.

homeAddress.postalCode

The postal code associated with the customers home address.

homeAddress.country

The country associated with the customers home address.

5 External REST MVC Service Call Examples

Parameter

Description

homeAddress.phoneNumber

The phone number of the customers 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 customers home address.

homeAddress.faxNumber

A fax number associated with the customers 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.

5 External REST MVC Service Call Examples

119

120

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 customers e-mail address.

password

The customers password.

confirmPassword

Re-enter the customers password to verify.

login

The customers log in name.

dateOfBirth

The customers date of birth.

gender

The customers gender.

homeAddress.address1

The first address line of the customers home address.

homeAddress.address2

The second address line of the customers home address.

homeAddress.address3

The third address line of the customers home address.

homeAddress.city

The city associated with the customers home address.

homeAddress.state

The state associated with the customers home address.

homeAddress.postalCode

The postal code associated with the customers home address.

homeAddress.country

The country associated with the customers home address.

homeAddress.phoneNumber

The phone number of the customers 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 customers home address.

homeAddress.faxNumber

A fax number associated with the customers 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

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"

5 External REST MVC Service Call Examples

121

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": [{

122

5 External REST MVC Service Call Examples

"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",

5 External REST MVC Service Call Examples

123

"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 customers shopping cart. The path for
this actor is /atg/commerce/order/purchase/CartModifierActor.
This actor contains the following actor-chains:

124

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

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.

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},
{\"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/

5 External REST MVC Service Call Examples

125

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

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"

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 "{

126

5 External REST MVC Service Call Examples

\"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"

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

5 External REST MVC Service Call Examples

127

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.

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

128

5 External REST MVC Service Call Examples

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

getAllCommerceItemShippingInfos

Obtains all of the Commerce Item Shipping Info (CISI).

applyShippingGroups

Applies the shipping group.

splitShippingInfos

Splits the shipping between specified shipping groups.

Displaying Shipping Groups

The GetShippingGroups actor-chain displays all of the shipping groups that are available.

5 External REST MVC Service Call Examples

129

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,
"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": [],

130

5 External REST MVC Service Call Examples

"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"
"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"

5 External REST MVC Service Call Examples

131

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.

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\":

132

5 External REST MVC Service Call Examples

\"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.

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.

5 External REST MVC Service Call Examples

133

Parameter

Description

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:

134

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.

phoneNumber

The phone number of the customer associated with this shipping group.

5 External REST MVC Service Call Examples

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.

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.

5 External REST MVC Service Call Examples

135

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
}}}

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"

136

5 External REST MVC Service Call Examples

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",
"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.

5 External REST MVC Service Call Examples

137

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
}]
},
"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,

138

5 External REST MVC Service Call Examples

"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
}]
},
"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,

5 External REST MVC Service Call Examples

139

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

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:

140

5 External REST MVC Service Call Examples

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.

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:

5 External REST MVC Service Call Examples

141

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.

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:

142

5 External REST MVC Service Call Examples

Actor-Chain

Description

getCurrentCatalogRootCategories

Obtains the users current catalog and root categories.

getCategory

Displays the users sub-categories.

getProduct

Views a product by Product ID.

Getting the Users Current Catalog

The getCurrentCatalogRootCategories actor-chain looks at the users 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
}
]}

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 users 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 users catalog or current site, the chain will return an error message.

5 External REST MVC Service Call Examples

143

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,
"displayName": "Shoes",
"type": null
},
{
"id": "cat10016",
"description": null,
"defaultParentCategory": null,
"displayName": "Home Accents",
"type": null
}
],

144

5 External REST MVC Service Call Examples

"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",
"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"
}],

5 External REST MVC Service Call Examples

145

"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"
}}

Searching a Catalog
The catalog search REST MVC call uses Endeca catalog search. For information on Endeca catalog searches, refer
to the Platform Installation and Configuration Guide.
To initiate a catalog search call:

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"

"http://localhost:8280/crs/browse?Ntt=shirt&format=json"

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 users 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 Lowest and Highest Prices for a Product

The productPriceRanges actor-chain returns the lowest and highest prices for a specific product.

146

5 External REST MVC Service Call Examples

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 Product by 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.

skuId

The SKU ID to use.

Get Prices by Product 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,}

Working with Orders

There are a number of REST services that have been created that allow you to work with orders.

5 External REST MVC Service Call Examples

147

Looking Up an Order by Order ID or User ID

The OrderLookupActor is used to look up the current users 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,
"currencyCode": "USD",
"currentPriceDetailsSorted": [{
"amount": 119.2,
"currencyCode": "USD",
"quantity": 1,
"detailedUnitPrice": 119.2
}]
},
"quantity": 1,
"catalogRefId": "xsku2126",
"productId": "xprod2126"
}],
"totalCommerceItemCount": 1
}}

148

5 External REST MVC Service Call Examples

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 users 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

"{\"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:

5 External REST MVC Service Call Examples

149

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.

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,

150

5 External REST MVC Service Call Examples

"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",
"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,

5 External REST MVC Service Call Examples

151

"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
},
"paymentGroups": [{
"amount": 0,
"currencyCode": null,
"expirationMonth": "1",
"expirationYear": "2014",
"paymentId": "pg140002",
"creditCardNumber": "1111",
"expirationDayOfMonth": null,
"billingAddress": {
"middleName": null,
"lastName": "Smith",
"ownerId": null,
"state": "MA",

152

5 External REST MVC Service Call Examples

"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
}}

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.

5 External REST MVC Service Call Examples

153

Parameter

Description

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

154

5 External REST MVC Service Call Examples

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 291) section in the Internal REST MVC
Service Call Examples (page 177) 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 orders 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 orders return request.

nonReturnItemDetails

Displays refund adjustments that were applied to non-return

items.

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

5 External REST MVC Service Call Examples

155

StartReturnExchangeProcess form handler. For information on the internal createReturns actor-chain,

refer to the Creating a Return (page 293) 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 actorchain takes the input from an updated JSON-formatted return request and then uses that input to set the serverside shipping group lists 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\",
\"quantityToReturn\":1,\"returnReason\":\"defective\",\"quantityToExchange\":
0}]}]}}}" "http://localhost:8181/rest/model/atg/commerce/custsvc/returns/
CSRReturnsActor/selectItems"

156

5 External REST MVC Service Call Examples

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,
"description":"Boyfriend Jeans",
"quantityToReturn":1,
"actualShippingRefundShare":6.31,
"suggestedShippingRefundShare":6.31,
"commerceItemId":"xci1000051",

5 External REST MVC Service Call Examples

157

"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 156).
Parameters: None

Obtain Return Reason Codes Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"
"http://localhost:8181/rest/model/atg/commerce/custsvc/returns/ReturnsActor/
returnReasons"

The server may return a response similar to the following:

158

5 External REST MVC Service Call Examples

{
"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"
"http://localhost:8181/rest/model/atg/commerce/custsvc/returns/ReturnsActor/
cancelReturnRequest"

5 External REST MVC Service Call Examples

159

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/
applyRefunds"

160

5 External REST MVC Service Call Examples

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
"{\"orderId\":\"o2620001\"}" "http://localhost:8280/rest/model/atg/commerce/
custsvc/returns/ReturnsActor/returnsHistory"

5 External REST MVC Service Call Examples

161

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.

162

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.

5 External REST MVC Service Call Examples

Parameter

Description

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:

{"promotionsLost":"promo50012"}

5 External REST MVC Service Call Examples

163

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 126).
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.

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

profileGiftlists

Views the current profiles list of gift lists.

Creating a Gift List

The createGiftlist actor-chain creates a gift list.

164

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.

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.

5 External REST MVC Service Call Examples

Parameter

Description

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/
model/atg/commerce/gifts/GiftlistActor/updateGiftlist"

Adding Items to a Gift List

The addItemToGiftlist actor-chain adds an item to a gift list.

5 External REST MVC Service Call Examples

165

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"

Removing Items from a Gift List

The removeItemFromGiftlist actor-chain removes an item from a gift list.

166

Parameter

Description

giftlistId

The ID of the gift list from which the items will be removed.

5 External REST MVC Service Call Examples

Parameter

Description

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.

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:

5 External REST MVC Service Call Examples

167

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 Profiles List of Gift Lists

The profileGiftlist actor-chain views the current profiles list of gift lists.
Parameters: None

View Current Profiles 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"

The server response may be similar to the following:

{"giftlists": [
{
"name": "Birthday",
"repositoryId": "xgl20004"

168

5 External REST MVC Service Call Examples

},
{
"name": "Anniversary",
"repositoryId": "gl430003"
}
]}

Viewing a Gift List

The GiftlistLookupActor is used to view a customers 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 Lists Items

The GiftlistLookupActor is used to view the items within a customers gift list. This actor is located at: /atg/
commerce/gifts/GiftlistLookupActor, and contains the items actor-chain.

Parameter

Description

giftlistId

The ID of the gift list to view.

5 External REST MVC Service Call Examples

169

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
},
{
"repositoryId":"xgi10007",
"productId":"xprod2116",
"siteId":"homeSite",
"skuId":"xsku2116",
"quantity":1
},

170

5 External REST MVC Service Call Examples

{
"repositoryId":"xgi10008",
"productId":"xprod2138",
"siteId":"homeSite",
"skuId":"xsku2138",
"quantity":1
}
]}

Viewing a Wish List

The GiftlistLookupActor is used to view a customers 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
},
{
"repositoryId":"xgi10004",
"productId":"xprod1047",
"siteId":"storeSiteUS",
"skuId":"xsku1244",
"quantity":1
},
{

5 External REST MVC Service Call Examples

171

"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 customers gift list. This actor is located at: /atg/commerce/
gifts/GiftlistSearchActor, and contains the search actor-chain.

172

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.

resultsPerPage

Sets the number of results to display per page.

state

The state or province of the billing address.

5 External REST MVC Service Call Examples

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
}
]}

5 External REST MVC Service Call Examples

173

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"

The server response may be similar to the following:

{
"FashionIsland": {
"distance": 0,
"postalCode": "92660",

174

5 External REST MVC Service Call Examples

"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 users profile locale. The path of this actor is /atg/
commerce/util, and it contains the states actor-chain.

Parameter

Description

countryCode

Identifies the country code of a specific customer.

5 External REST MVC Service Call Examples

175

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"
},
...
}
]}

176

5 External REST MVC Service Call Examples

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

6 Internal REST MVC Service Call Examples

177

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 environments 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}

178

6 Internal REST MVC Service Call Examples

Logging Agents In and Out

The AgentProfileActor is located at /atg/agent/userprofiling/ and contains the following actorchains:

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 agents 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 login
combination is incorrect.","errorCode":"invalidPassword"}]}

Logging Out Agents

The logout actor-chain is used to log the agent out of the site.
Parameters: None

6 Internal REST MVC Service Call Examples

179

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 agents 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"

180

6 Internal REST MVC Service Call Examples

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:

6 Internal REST MVC Service Call Examples

181

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:

182

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

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:

6 Internal REST MVC Service Call Examples

183

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 if
we 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 183)
example for information on the TicketingActor.
The TicketActor contains the following actor-chains:

184

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

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.

6 Internal REST MVC Service Call Examples

185

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.

186

Parameter

Description

ticketId

The ID of the ticket to associate.

associatedTicketId

The ID of the associated ticket.

6 Internal REST MVC Service Call Examples

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

6 Internal REST MVC Service Call Examples

187

"{\"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.

188

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

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"

6 Internal REST MVC Service Call Examples

189

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.

190

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

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.

6 Internal REST MVC Service Call Examples

191

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.

192

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

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.

6 Internal REST MVC Service Call Examples

193

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.

194

6 Internal REST MVC Service Call Examples

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",

6 Internal REST MVC Service Call Examples

195

"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

196

6 Internal REST MVC Service Call Examples

},
{
"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,

6 Internal REST MVC Service Call Examples

197

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

198

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

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\":\"\",

6 Internal REST MVC Service Call Examples

199

\"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 tickets 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 actorchain:

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 "{

200

6 Internal REST MVC Service Call Examples

\"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 customers login.

password

The customers password.

dateOfBirth

The customers 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 users 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 customers address.

6 Internal REST MVC Service Call Examples

201

Parameter

Description

address.address2

The second address field associated with the customers address.

address.city

The city associated with the customers address.

address.companyName

A company name associated with the customers address.

address.country

A country associated with the customers address.

address.county

A county associated with the customers address.

address.jobTitle

A job title associated with the customers address.

address.postalCode

The postal code associated with the customers address.

address.faxNumber

A fax number associated with the customers 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 customers address.

address.prefix

A prefix associated with the customer, such as Mr. or Dr.

address.state

The state associated with the customers 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 users 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\":

202

6 Internal REST MVC Service Call Examples

\"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 customers date of birth.

address.address1

The first address field associated with the customers address.

address.address2

The second address field associated with the customers address.

address.city

The city associated with the customers address.

address.companyName

A company name associated with the customers address.

address.country

A country associated with the customers address.

address.county

A county associated with the customers address.

address.jobTitle

A job title associated with the customers address.

address.postalCode

The postal code associated with the customers address.

address.faxNumber

A fax number associated with the customers 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 customers address.

address.prefix

A prefix associated with the customer, such as Mr. or Dr.

address.state

The state associated with the customers address.

address.suffix

A suffix associated with the customer, such as Jr.

6 Internal REST MVC Service Call Examples

203

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.

204

6 Internal REST MVC Service Call Examples

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"
},

6 Internal REST MVC Service Call Examples

205

{
"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.

206

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

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.

6 Internal REST MVC Service Call Examples

207

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"}

208

6 Internal REST MVC Service Call Examples

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.

6 Internal REST MVC Service Call Examples

209

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 customers profile.

deleteCreditCard

Deletes a credit card from a customers 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.

210

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

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.

6 Internal REST MVC Service Call Examples

211

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 "{

212

6 Internal REST MVC Service Call Examples

\"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 Customers Shopping Cart

The /atg/commerce/custsvc/order/ShoppingCartActor contains a single detailed actor-chain, which
is used to view or review a customers 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/

6 Internal REST MVC Service Call Examples

213

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",

214

6 Internal REST MVC Service Call Examples

"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",

6 Internal REST MVC Service Call Examples

215

"amount": 0,
"relationshipType": "SHIPPINGQUANTITY",
"returnedQuantity": 0,
"shippingGroupId": "sg110004",
"commerceItemId": "ci10000001",
"quantity": 1
}],
"totalCommerceItemCount": 1
}}

Working with a Customers Shopping Cart

The CartModifierActor contains several actor-chains that modify the customers shopping cart. The path for
this actor is /atg/commerce/custsvc/order/CartModifierActor.
This actor contains the following actor-chains:

216

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

Actor-Chain

Description

changeSKUs

Changes the SKU of one or more commerce items in

the current order.

Adding Multiple Items to a Customers Shopping Cart

The addMultipleItemsToOrder actor-chain is used when adding more than one item to the customers
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"

6 Internal REST MVC Service Call Examples

217

Adding Items to a Customers Shopping Cart

The addItemToOrder actor-chain is used to add a single item to a customers shopping cart. It also is used to
add an item from a customers 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 Customers 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 Customers 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 Customers 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/

218

6 Internal REST MVC Service Call Examples

addItemToOrder"

Add Item From Customers 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 Customers Shopping Cart by SKU ID

The setOrder actor-chain updates the quantity of items within the customers shopping cart using SKU IDs.

Parameter

Description

removalCatalogRefIds

The optional list of catalog reference IDs (SKU ID) to remove from the
order.

Update Customers 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 Customers Shopping Cart by Commerce ID

The setOrderByCommerceId actor-chain updates the quantities of items within the customers shopping cart
using the commerce ID. Note that this actor-chain is also used to perform a price override. Refer to the Adjusting
a Customers Order (page 263) section for information on price overrides.

Parameter

Description

removalCommerceIds

The optional list of commerce item IDs to remove from the order.

Update Customers 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"

6 Internal REST MVC Service Call Examples

219

Updating the Customers Shopping Cart By Shipping Group Relationship ID

The setOrderByRelationshipId actor-chain is used to update the quantities of items within the customers
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 Customers 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 Customers 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 Customers 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 Customers Shopping Cart

The removeItemFromOrder actor-chain removes items from the customers shopping cart using the commerce
ID.

220

6 Internal REST MVC Service Call Examples

Parameter

Description

removalCommerceIds

The list of commerce item IDs to remove from the order.

Remove Item From Customers 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 Customers Shopping Cart By Relationship ID

The removeItemFromOrderByRelationshipId actor-chain is used to remove items from the customers
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 Customers 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 orders 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 orders
commerce ID quantities are passed in to initiate the checkout process.

6 Internal REST MVC Service Call Examples

221

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

222

Actor-Chain

Description

getShippingGroups

Initializes and retrieves avilable shipping groups.

6 Internal REST MVC Service Call Examples

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.

6 Internal REST MVC Service Call Examples

223

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.

224

6 Internal REST MVC Service Call Examples

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"

6 Internal REST MVC Service Call Examples

225

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:

226

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

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.

6 Internal REST MVC Service Call Examples

227

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

228

Actor-Chain

Description

getPaymentGroups

Displays the customers 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

Display the Customers Payment Groups

The getPaymentGroups actor-chain is used to display the customers 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.

6 Internal REST MVC Service Call Examples

229

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"
},
{

230

6 Internal REST MVC Service Call Examples

"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 "{

6 Internal REST MVC Service Call Examples

231

\"claimCode\": \"sc36b60\" }" "http://localhost:8280/rest/model/atg/commerce/

custsvc/order/PaymentGroupActor/claimItem"

Claiming a Customers 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 Customers 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 customers
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\":

232

6 Internal REST MVC Service Call Examples

\"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 customers 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 Customers 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.

6 Internal REST MVC Service Call Examples

233

Parameter

Description

creditCardNumber

Adds the new credit card number.

expirationMonth

Adds the new credit cards expiration month.

expirationYear

Adds the new credit cards 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.

234

Parameter

Description

creditCardType

Identifies the address to delete.

creditCardNumber

Adds the new credit card number.

expirationMonth

Adds the new credit cards expiration month.

expirationYear

Adds the new credit cards 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

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.

6 Internal REST MVC Service Call Examples

235

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.

236

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

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,

6 Internal REST MVC Service Call Examples

237

"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"
}}

238

6 Internal REST MVC Service Call Examples

}}

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.

6 Internal REST MVC Service Call Examples

239

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"

240

6 Internal REST MVC Service Call Examples

}
]},
"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.

6 Internal REST MVC Service Call Examples

241

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 "{

242

6 Internal REST MVC Service Call Examples

\"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"
},

6 Internal REST MVC Service Call Examples

243

{
"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 251)
section.

validateTemplateOrder

Validates a scheduled order template order. For information on this actorchain, refer to the Working with Scheduled Orders (page 251) 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:

244

6 Internal REST MVC Service Call Examples

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 251) section.

Commit Customers 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 Customers Order

The ConfirmOrderActor is used to confirm a customers 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 Customers 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",

6 Internal REST MVC Service Call Examples

245

"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,

246

6 Internal REST MVC Service Call Examples

"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.
This actor contains the orderConfirmation actor-chain.

6 Internal REST MVC Service Call Examples

247

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

248

6 Internal REST MVC Service Call Examples

"{ \"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 311) 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 Customers Current Order

The OrderNoteActor is used to add a note to a customers current order. The path to this actor is: /atg/
commerce/custsvc/order/.

6 Internal REST MVC Service Call Examples

249

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 Customers Original Order

The OriginalOrderNoteActor is used to add a note to a customers 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 Customers 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.

250

6 Internal REST MVC Service Call Examples

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 until
11/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 200) section. To set the current
order, refer to the Selecting an Order to Work On (page 241) section. To commit and validate the order, refer to
the Saving or Committing an Order (page 244) 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.

6 Internal REST MVC Service Call Examples

251

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.

252

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

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:

6 Internal REST MVC Service Call Examples

253

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.

254

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

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 200) section. To set the
current order, refer to the Selecting an Order to Work On (page 241) section.
This actor uses the duplicateAndSumbit actor-chain to identify the template of the scheduled order and then
submit it.

6 Internal REST MVC Service Call Examples

255

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.

256

6 Internal REST MVC Service Call Examples

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

6 Internal REST MVC Service Call Examples

257

"{ \"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.

258

6 Internal REST MVC Service Call Examples

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"

6 Internal REST MVC Service Call Examples

259

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 customers 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. :

260

6 Internal REST MVC Service Call Examples

Parameter

Description

itemId

The ID of the of the item.

templateId

The ID of the template.

profileId

The ID of the users profile.

siteIds

The IDs of the sites used in this scheduled order.

siteScope

The site scope used in this scheduled order.

Review a Templates 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 Templates 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:

6 Internal REST MVC Service Call Examples

261

{
"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 Users 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:

262

Parameter

Description

profileId

The ID of the of the users 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

View a Users 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 Customers 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 customers 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.

delteAdjustment

Used to delete an adjustment from an order.

Adjusting a Customers Order

The addAdjustment actor-chain is used to issue an adjustment to a customers order.

Parameter

Description

adjustmentAmount

The amount of the adjustment.

adjustmentNote

A note to provide a description for the adjustment.

adjustmentReasonCode

The adjustment reason code used for this adjustment.

6 Internal REST MVC Service Call Examples

263

Parameter

Description

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 Customers 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 Items Price in the Customers 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

Override Price Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"

264

6 Internal REST MVC Service Call Examples

"http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/
setOrderByCommerceId?ci172000006=1&IPO:ci172000006=19.99"

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 users current catalog and root categories.

getCategory

Displays the users sub-categories.

getProduct

Views a product by Product ID.

Getting the Customers 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

6 Internal REST MVC Service Call Examples

265

}
]}

Browsing the Customers Catalog By Category ID

The getCatagory actor-chain allows the agent to browse the customers 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.

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 Customers Catalog By Product ID

The getProduct actor-chain allows the agent to browse the customers 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/

266

6 Internal REST MVC Service Call Examples

custsvc/catalog/ProductCatalogActor/getProduct"

Search a Catalog
The catalog search REST call uses Endeca catalog search. For information on Endeca catalog searches, refer to
the Commerce Reference Store Installation and Configuration Guide
Note: When a Commerce Service Center agent performs a search, the agents profile is the current profile, but
when Oracle Commerce Platform calls the Endeca catalog search API, the customer profile becomes the current
profile.
To initiate a catalog search call:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json"

"http://localhost:8280/crs/browse?Ntt=shirt&format=json"

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.

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"

6 Internal REST MVC Service Call Examples

267

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 users current catalog.

setDefaultCatalog

Resets the users 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/
atg/commerce/custsvc/environment/EnvironmentChangeActor/setCurrentCatalog"

Retrieving the Current Catalog

The getCurrentCatalog actor-chain retrieves the users 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 users current default catalog.
Parameters: None

268

6 Internal REST MVC Service Call Examples

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 users 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:

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, }

6 Internal REST MVC Service Call Examples

269

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 Customers 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.
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 users current price list.

setDefaultPriceList

Resets the users 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.

270

6 Internal REST MVC Service Call Examples

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 users 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 users current default price list.
Parameters: None

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.

6 Internal REST MVC Service Call Examples

271

Parameter

Description

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 Customers Promotions

The PromotionWalletActor is used to work with customers promotion information. The path to this actor is:
/atg/commerce/custsvc/promotion/PromotionWalletActor.
This actor contains the following actor-chains:

272

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.

6 Internal REST MVC Service Call Examples

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,
"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"
}
]}

6 Internal REST MVC Service Call Examples

273

Updating Prices After Promotions

The updatePrice actor-chain returns an updated price of the customers 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"

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"

274

6 Internal REST MVC Service Call Examples

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.

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/

6 Internal REST MVC Service Call Examples

275

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",
"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 actorchain.

276

Parameter

Description

keyword

The keyword used to search for promotions.

6 Internal REST MVC Service Call Examples

Parameter

Description

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"
}
]}

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 206). 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.

6 Internal REST MVC Service Call Examples

277

Parameter

Description

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

278

6 Internal REST MVC Service Call Examples

The response may be similar to the following:

{\"ChangedPromotions\": { \"id\" : \"promo50012\", \"displayName\" : \"10 off
orders over $100\" }

Working with Customers Gift Lists

The following actors are used to work with a customers gift or wish list. For information on adding a gift or wish
list item to a shopping cart, refer to Add Item From Customers Gift List Example (page 218) and Add Item
From Customers Wish List Example (page 219).
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 Customers Gift or Wish List

The createGiftlist actor-chain creates a gift list or a 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.

6 Internal REST MVC Service Call Examples

279

Parameter

Description

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 customers address.

state

The state or province of the customers address.

postalCode

The postal code of the customers address.

country

The country of the customers 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"

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 "{

280

6 Internal REST MVC Service Call Examples

\"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 Customers Gift or Wish List

The updateGiftlist actor-chain allows an agent to edit a customers 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.

middleName

The middle name or initial of the customer.

lastName

The last name of the customer.

address1

The first address field of the customer.

6 Internal REST MVC Service Call Examples

281

Parameter

Description

address2

The second address field of the customer.

city

The city of the customers address.

state

The state or province of the customers address.

postalCode

The postal code of the customers address.

country

The country of the customers 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 Customers Gift List

The addItemToGiftlist actor-chain allows an agent to add an item to a customers 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 "{
\"giftlistId\": \"gl380011\", \"productId\": \"xprod1015\", \"catalogRefIds\" :
\"xsku1043\",\"quantity\": \"2\", \"siteId\": \"homeSite\"}"
"http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/
addItemToGiftlist"

282

6 Internal REST MVC Service Call Examples

Adding Items to a Customers Wish List

The addItemToWishlist actor-chain allows an agent to add an item to the active customers 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 Customers 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 Customers Gift List

The removeItemFromGiftlist actor-chain allows an agent to remove an item from a customers 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 Customers 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"

Removing Items from a Customers Wish List

The removeItemFromWishlist actor-chain enables an agent to remove an item from a customers wish list.

6 Internal REST MVC Service Call Examples

283

Parameter

Description

giftitemId

The ID of the items to be removed from the wish list.

Remove Item from Customers 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 Customers 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 Customers 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 Customers 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.

Delete a Customers Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{

284

6 Internal REST MVC Service Call Examples

\"giftlistId\": \"gl220010\" }" "http://localhost:8180/rest/model/atg/commerce/

custsvc/gifts/CSRGiftlistActor/deleteGiftlist"

Viewing a Customers Gift List

The GiftlistLookupActor enables an agent to view a customers 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 customers 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",
}
}

The giftlistItems actor-chain contains the following parameter:

6 Internal REST MVC Service Call Examples

285

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 Customers Wish List

The ServiceCustomerProfileActor enables an agent to view a customers gift or wish list. This actor is
located at /atg/userprofiling/ServiceCustomerProfileActor, and contains the viewWishlist actorchain.
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 Customers Gift List

The CSRGgiftlistSearchActor is used to find a customers gift list. This actor is located at /atg/commerce/
gifts/ and contains the search actor-chain.

286

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.

resultsPerPage

The number of results that are displayed per page.

currentPage

The paging results of the search to display.

6 Internal REST MVC Service Call Examples

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
}
]
}

6 Internal REST MVC Service Call Examples

287

Viewing a List of Customers Gift or Wish Lists

The GiftlistTableActor allows an agent to display a list of all of the customers 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,
"repositoryId": "gl130274"
"addressId": "230327"
}]
}

288

6 Internal REST MVC Service Call Examples

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 externalbased REST calls. Refer to the Working with In-Store Pickup (page 174) 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 Customers Shopping
Cart (page 218).

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"
"http://localhost:8180/rest/model/atg/commerce/custsvc/approvals/
ViewAllPendingApprovalsActor/viewAllPendingApprovals"

The response may be similar to the following:

"pendingApprovals":
{
"creationDate":

6 Internal REST MVC Service Call Examples

289

{
"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.

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

290

6 Internal REST MVC Service Call Examples

/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.
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 actorchain.
Modify the default refund amounts by calling the ModifyRefundValuesActor.

6 Internal REST MVC Service Call Examples

291

 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:

292

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.

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 orders return request.

nonReturnItemDetails

Displays refund adjustments that were applied to non-return items.

6 Internal REST MVC Service Call Examples

Actor-Chain

Description

changedPromotions

Identifies promotions that have changed during the return process.

For information on this actor-chain, refer to the Displaying Changed
Promotions (page 278) 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 155) 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":[
{
"returnItemId":"xcr10101",
"quantityShipped":1,
"quantityReturned":0,
"quantityAvailable":1,
"description":"Boyfriend Jeans",
"commerceItemId":"xci1000051",
"catalogRefId":"xsku2519_2"
},
{
"returnItemId":"xcr10102",
"quantityShipped":1,
"quantityReturned":0,
"quantityAvailable":1,

6 Internal REST MVC Service Call Examples

293

"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 lists 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 297) section for
information on retrieving reason codes.
This actor-chain contains the following parameters:

294

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.

6 Internal REST MVC Service Call Examples

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",
"amount":113.62,
"maximumRefundAmount":131.85
},
{
"refundType":"storeCredit",
"amount":0,
"maximumRefundAmount":-1
}
],
"returnItemCount":2,
"actualTaxRefund":0,
"returnItemList":[
{
"quantityToExchange":0,

6 Internal REST MVC Service Call Examples

295

"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,
"orderId":"xco30045",
"profile":{
"middleName":null,
"lastName":"Smith",
"id":"se-570085",
"login":"jsmith@example.com",
"firstName":"Joe"
}
}
}

296

6 Internal REST MVC Service Call Examples

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 294).
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"

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

6 Internal REST MVC Service Call Examples

297

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 items 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\"
:{\"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

298

6 Internal REST MVC Service Call Examples

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\":
\"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.

6 Internal REST MVC Service Call Examples

299

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.

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

300

6 Internal REST MVC Service Call Examples

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":[
{
"methods":[
{
"methodType":"creditCard"
}
],
"requestId":"xc100005",
"replacementOrderId":null,
"items":[
{
"requestId":"xc100005",
"returnItemId":"xc100007"
},
{
"requestId":"xc100005",
"returnItemId":"xc100008"
},
{
"requestId":"xc100005",

6 Internal REST MVC Service Call Examples

301

"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.
This actor contains the updateCreditCardForReturns actor-chain. This actor-chain depends on the
ReturnsActor createReturn actor-chain to obtain the correct information.

302

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.

6 Internal REST MVC Service Call Examples

Parameter

Description

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"

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:

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.

6 Internal REST MVC Service Call Examples

303

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"

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:

304

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.

6 Internal REST MVC Service Call Examples

Actor-Chain

Description

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 the
email\" }" "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.

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.

6 Internal REST MVC Service Call Examples

305

Parameter

Description

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\" : \"LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tL
S0xMDU3MDczMDI5NjAxNTY2MTEzNjkyMDY4MTQNCkNvbnRlbnQtRGlzcG9zaXRpb246IGZvcm0tZGF0YTs
gbmFtZT0iX2R5bmNoYXJzZXQiDQoNClVURi04DQotLSS0tLS0tLS0tLS0tMTA1NzA3MzAyOTYwMTU2NjEx
MzY5MjA2ODE0LS0NCg==\", \"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.

306

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.

6 Internal REST MVC Service Call Examples

Parameter

Description

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

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 HTML
goes 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.

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"

6 Internal REST MVC Service Call Examples

307

"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"
},
"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.

308

6 Internal REST MVC Service Call Examples

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.

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

309

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/
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":[],

310

6 Internal REST MVC Service Call Examples

"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
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
}

6 Internal REST MVC Service Call Examples

311

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>
<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/

312

6 Internal REST MVC Service Call Examples

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>

6 Internal REST MVC Service Call Examples

313

314

6 Internal REST MVC Service Call Examples

Part II. Legacy REST Web Services

This 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 applicationfor 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.

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 343) and Invoking Legacy REST Component Methods (page 345).

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/

7 Using Legacy REST Web Services

317

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 354).

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 381).

318

7 Using Legacy REST Web Services

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 319) and Logging In as an Internal
User (page 320).

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 319) and Logging In as an Internal User (page 320)
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 323) and Invoking Legacy REST Component Methods (page 345).

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)

7 Using Legacy REST Web Services

319

*
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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9y
bUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
* 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 domain
myserver, 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 323) and Invoking Legacy REST Form Handlers (page 346).

320

7 Using Legacy REST Web Services

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 321).

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

7 Using Legacy REST Web Services

321

> 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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAsU2VhcmNoLzEwLjAg
WyBQbGF0Zm9ybUxpY2Vuc2UvMCBT
ZWFyY2hBZG1pbkxpY2Vuc
2UvMCBQdWJsaXNoaW5nTGljZW5zZS8wIEIyQ0xpY2Vuc2UvMCAgXQ==
< 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
*
*
*
>
>
>
>
>
>
>
<
<
<
<

322

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

QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY
2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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 343)
Invoking Legacy REST Component Methods (page 345)
Working with Repositories in Legacy REST (page 354)

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

7 Using Legacy REST Web Services

323

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 345).

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 318).

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.

324

7 Using Legacy REST Web Services

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 323).

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']}" \

7 Using Legacy REST Web Services

325

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-restappend-multi-values control parameter. For information this parameter, refer to the Using Multiple Values in
Input (page 325) 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.

326

7 Using Legacy REST Web Services

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-appendmulti-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-restappend-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-

7 Using Legacy REST Web Services

327

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=

328

7 Using Legacy REST Web Services

< 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-classdescriptor 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-classdescriptor 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>

7 Using Legacy REST Web Services

329

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=838bac4608584930c
f177410e3b46448; 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=

330

7 Using Legacy REST Web Services

< 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 331).

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

7 Using Legacy REST Web Services

331

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

332

7 Using Legacy REST Web Services

</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=
QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc
2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==
< Content-Type: application/json;charset=UTF-8

7 Using Legacy REST Web Services

333

< 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
339).
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 domain
myserver, path /, expire 0
< Set-Cookie: JSESSIONID=A2C79A00F7194A1F113604FD1C4BE7DD; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2
Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< Content-Type: application/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Fri, 05 Nov 2010 21:50:44 GMT

334

7 Using Legacy REST Web Services

<
<?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 domain
myserver, path /, expire 0
< Set-Cookie: JSESSIONID=9D730DE9D4A7C250994F20363ACC3FA6; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybU
xpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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>

7 Using Legacy REST Web Services

335

<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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9yb
UxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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:

336

7 Using Legacy REST Web Services

--&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

7 Using Legacy REST Web Services

337

< Server: Apache-Coyote/1.1

< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
* Replaced cookie JSESSIONID="F60503E5A6051C18D119B6CE470F9591" for domain
myserver, path /, expire 0
< Set-Cookie: JSESSIONID=F60503E5A6051C18D119B6CE470F9591; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2V
uc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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
>

338

7 Using Legacy REST Web Services

< 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 domain
12.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:

7 Using Legacy REST Web Services

339

<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 339). If you do not want to expand date properties, you can suppress
property expansion for them. See Suppressing Property Expansion in Legacy REST (page 368).

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.

340

7 Using Legacy REST Web Services

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=
QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxp
Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==
< 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> Status
report</p><p><b>message</b> <u>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
</u></p><p><b>description</b> <u>The request sent by the client was syntactically
incorrect (atg.beans.PropertyNotFoundException: Can't find property named:

7 Using Legacy REST Web Services

341

fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find property

named: 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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9y
bUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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 on
line 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 not
allowed 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>

342

7 Using Legacy REST Web Services

<u>org.dom4j.DocumentException: Error on line 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 not allowed in prolog. Nested exception: Content
is not allowed in prolog.</u></p><p><b>description</b> <u>The server encountered
an internal error (org.dom4j.DocumentException: Error on line 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 not allowed in prolog. Nested
exception: Content is not allowed in prolog.) that prevented it from fulfilling
this 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 317).
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: */*

7 Using Legacy REST Web Services

343

> 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=
QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxp
Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==
< 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 323).

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 317).

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>" \

344

7 Using Legacy REST Web Services

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=
QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxp
Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==
< 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 323).

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 317).

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.

7 Using Legacy REST Web Services

345

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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxp
Y2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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.

346

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 347).

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 317).

7 Using Legacy REST Web Services

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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2
Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
* 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" for
domain 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

7 Using Legacy REST Web Services

347

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 348).

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

348

7 Using Legacy REST Web Services

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 348).

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

7 Using Legacy REST Web Services

349

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 351).
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 351).

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 351).

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 351). The code of the JSP itself is shown in Example Legacy REST Web Services
JSP (page 353).
$ curl -v -b cookies.txt -X GET http://myserver:7003/rest/service/
atg/AnyComponent/xprod2083,foo

350

7 Using Legacy REST Web Services

* 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=838bac4608584930c
f177410e3b46448; 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 353).
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 351).
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
352).

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.

7 Using Legacy REST Web Services

351

<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 format
urlTemplateFormat=/rest/service/atg/AnyComponent/{item.id},{mystring}
# Regex that matches above format
indirectRegex=.*/rest/service/atg/AnyComponent/([^/].*?),([^/].*?)$
# Regex elements
regexElementList=item | id | /atg/AnyComponent\:product, mystring | string
# Forward Url template
forwardUrlTemplateFormat=/mymodule/WEB-INF/rest/myRestJsp.jsp?
productId\={item.id}&myString\={mystring}
# Web App registry
webAppRegistry=/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

352

7 Using Legacy REST Web Services

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>

7 Using Legacy REST Web Services

353

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 items datafor 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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc
2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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"?>

354

7 Using Legacy REST Web Services

<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

7 Using Legacy REST Web Services

355

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

356

7 Using Legacy REST Web Services

> 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" for
domain myserver, path /, expire 0
< Set-Cookie: JSESSIONID=A8D99275B90B200E0913A8831E77A9F4; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc
2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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

7 Using Legacy REST Web Services

357

* 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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybU
xpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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 318).
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.

358

Request Component

Value

HTTP Method

POST

7 Using Legacy REST Web Services

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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9
ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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]

7 Using Legacy REST Web Services

359

<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/

360

7 Using Legacy REST Web Services

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 domain
myserver, path /, expire 0
< Set-Cookie: JSESSIONID=6A9888BA9F4035AF606AE7E40A435451; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm
9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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.

7 Using Legacy REST Web Services

361

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/130037
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=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=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9
ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< 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 servers configuration path. To customize it, create that file in your own module and
the servers XML combination functionality will combine all the filteringConfiguration.xml files.

362

7 Using Legacy REST Web Services

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"/>

7 Using Legacy REST Web Services

363

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

364

7 Using Legacy REST Web Services

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 362).
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 362).
The following filteringConfiguration.xml file defines a filtering template.

<rest-filtering>
<template id="myfiltertemplate" name="/atg/MyDog" default-include="true">

7 Using Legacy REST Web Services

365

<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 362).
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>"
}, ...
}, ...
}, ...

366

7 Using Legacy REST Web Services

], ...
}

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 371) and /atg/rest/output/XMLOutputCustomizer (page 372).
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:

7 Using Legacy REST Web Services

367

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 deeplynested properties but you do not want extensive, unnecessary detail for other properties. See Return
Depth (page 339). 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:

368

7 Using Legacy REST Web Services

 Suppressing Property Expansion for Java Classes (page 369)

Suppressing Property Expansion for Specific Properties (page 369)

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
362).
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.

7 Using Legacy REST Web Services

369

/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 331). 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 334). 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 348). 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 348).
The following example specifies that the form handler
properties should be included in the HTTP response to a
Web Services request.
returnFormHandlerPropertiesByDefault=true

370

7 Using Legacy REST Web Services

/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 340).
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 362).
This property affects requests that will return results
formatted with JSON markup. See Choosing Output
Markup (page 331).
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 362).
This property affects requests that will return results
formatted with JSON markup. See Choosing Output
Markup (page 331).
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.

7 Using Legacy REST Web Services

371

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 362).
This property affects requests that will return results
formatted with JSON markup. See Choosing Output
Markup (page 331).
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 362).
This property affects requests that will return results
formatted with JSON markup. See Choosing Output
Markup (page 331).
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 334).
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

372

7 Using 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 340).
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 362).
This property affects requests that will return results
formatted with XML markup. See Choosing Output
Markup (page 331).
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 362).
This property affects requests that will return results
formatted with XML markup. See Choosing Output
Markup (page 331).
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 362).
This property affects requests that will return results
formatted with XML markup. See Choosing Output
Markup (page 331).
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.

7 Using Legacy REST Web Services

373

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 362).
This property affects requests that will return results
formatted with XML markup. See Choosing Output
Markup (page 331).
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.
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 334).

showRestPaths

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

374

7 Using Legacy REST Web Services

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
325).
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 378).
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.

7 Using Legacy REST Web Services

375

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 319).

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>

376

7 Using Legacy REST Web Services

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

7 Using Legacy REST Web Services

377

<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 350). 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 subtree. 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/*">

378

7 Using Legacy REST Web Services

<default-acl value="Profile$role$restCommerceUser:read,write,execute"/>
</resource>
</rest-security>

7 Using Legacy REST Web Services

379

380

7 Using Legacy REST Web Services

Legacy Rest Client Libraries

The Legacy REST Web Services package includes two client libraries:
Java Client Library for Legacy REST (page 381)
ActionScript Client Library for Legacy REST (page 395)
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 390).

8 Legacy Rest Client Libraries

381

 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 390).

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 392).
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)

382

8 Legacy Rest Client Libraries

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 388).
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 319).

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:

8 Legacy Rest Client Libraries

383

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.

useInternalProfileForLogin
Tells 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 385).
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 386).

384

8 Legacy Rest Client Libraries

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 319).
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
import
import
import

atg.rest.client.RestClientException;
atg.rest.client.RestComponentHelper;
atg.rest.client.RestResult;
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);

8 Legacy Rest Client Libraries

385

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

386

8 Legacy Rest Client Libraries

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.

8 Legacy Rest Client Libraries

387

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)

388

8 Legacy Rest Client Libraries

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.

8 Legacy Rest Client Libraries

389

Other useful methods on the RestResult object are getResponseCode() and getResponseMessage().
These return the responses 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

390

8 Legacy Rest Client Libraries

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)

8 Legacy Rest Client Libraries

391

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)

392

8 Legacy Rest Client Libraries

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 atgrest-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 repositorys 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/

8 Legacy Rest Client Libraries

393

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 youd use them with getItems(). See Retrieving a Repository Item in
Legacy REST (page 355) for more information.
In the following example, the INDEX and COUNT keywords in the RQL language are used instead of the atg-restindex 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);

394

8 Legacy Rest Client Libraries

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 applications 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
}

8 Legacy Rest Client Libraries

395

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 381) section.

public static function getComponent(pComponentPath:String, pParams:Array,

pSession:RestSession, pResultHandler:Function,
pFaultHandler:Function):void
public static function getPropertyValue(pComponentPath:String, pProperty:String,
pParams:Object, pSession:RestSession,
pResultHandler:Function, pFaultHandler:Function):void
public static function setPropertyValue(pComponentPath:String, pProperty:String,
pValue:Object, pParams:Object,
pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void
public 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 381) section.

public static function getItem(pRepositoryPath:String, pItemDescriptorName:

String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:
Function, pFaultHandler: Function):void
public static function getItems(pRepositoryPath:String, pItemDescriptorName:
String, pParams:Object, pSession:RestSession, pResultHandler:Function,
pFaultHandler:Function):void
public static function executeRQLQuery(pRepositoryPath:String,
pItemDescriptorName:String, pRQL:String, pParams:Object, pSession:RestSession,
pResultHandler:Function, pFaultHandler: Function):void
public static function getPropertyValue(pRepositoryPath:String,
pItemDescriptorName:String, pItemId:String, pProperty:String,
pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:
Function):void

396

8 Legacy Rest Client Libraries

public static function setPropertyValue(pRepositoryPath:String,

pItemDescriptorName:String, pItemId:String, pProperty:String,
pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function,
pFaultHandler:Function):void
public static function createItem(pRepositoryPath:String,
pItemDescriptorName:String, pParams:Object, pSession:RestSession,
pResultHandler:Function, pFaultHandler:Function):void
public static function createItemWithId(pRepositoryPath:String,
pItemDescriptorName:String, pItemId:String,
pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:
Function):void
public 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 librarys 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):String
public static function convertIListToMultivalue(pValue:IList, pMultiValueType:
String, pComponentType:String, pFormat:String, pSession:RestSession):String
public 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 servers input format type. This can be retrieved from the session objects
inputFormat property.

pKeyType

ActionScript objects act as associative arrays (similar to java Maps), the

convertObjectToMultivalue() method takes a key type and value type.

pValueType

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.

8 Legacy Rest Client Libraries

397

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"],

398

8 Legacy Rest Client Libraries

"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()});
}

8 Legacy Rest Client Libraries

399

400

8 Legacy Rest Client Libraries

Index

A
ActivateScheduleActor, 256
ActiveCustomerProfileActor, 237
Actor
ActivateScheduleActor, Internal, 256
ActiveCustomerProfileActor, Internal, 237
AddressBookActor, Internal, 207
AddStoreCreditActor, Internal, 277
AvailablePricedShippingMethodsActor, Internal, 226
AvailableShippingMethodsActor, External, 133
CancelOrderActor, External, 149
CancelOrderActor, Internal, 242
CartModifierActor, External, 124
CartModifierActor, Internal, 216
ChangeCurrentCustomer, Internal, 206
ChangeOrderActor, Internal, 241
ChangePasswordActor, Internal, 180
ChangeSiteActor, Internal, 309
ClosenessQualifierActor, External, 154
ClosenessQualifierActor, Internal, 276
CommitOrderActor, External, 153
CommitOrderActor, Internal, 244
ConfirmLogoutActor, Internal, 180
ConfirmOrderActor, External, 150
ConfirmOrderActor, Internal, 245
CouponActor, External, 150
CouponActor, Internal, 232
CreateCreditCardActor, External, 140
CreateCreditCardActor, Internal, 233
CreateHardgoodShippingGroupActor, External, 133
CreateHardgoodShippingGroupActor, Internal, 226
CreditCardActor, Internal, 210
CSRCrossSellActor, Internal, 243
CSRGiftlistActor, Internal, 279
CSRGiftlistSearchActor, Internal, 286
CSRReturnsActor, Internal, 292
CSRScheduledOrderActor, Internal, 251
CSRScheduledOrderConfirmationActor, Internal, 258
CSRScheduledOrderInfoActor, Internal, 257
CustomerProfileActor, Internal, 201
CustomerSearchTreeQueryActor, Internal, 204

Index

DeactivateScheduleActor, Internal, 256

DefaultLoginPageActor, Internal, 181
DuplicateAndSubmitActor, Internal, 255
DuplicateOrderActor, Internal, 249
EndCallActor, Internal, 182
EnvironmentChangeActor, Internal, 268
GiftlistActor, External, 164
GiftlistLookupActor, External, 169
GiftlistLookupActor, Internal, 285
GiftlistSearchActor, External, 172
GiftListTableActor, Internal, 288
GlobalInfoActor, Internal, 307
IsScheduledOrderTemplateActor, Internal, 260
LostPromotionsActor, External, 163
LostPromotionsActor, Internal, 278
ManualAdjustmentsActor, Internal, 263
MessageToolsActor, Internal, 310
ModifyOrderActor, Internal, 248
ModifyRefundValuesActor, Internal, 303
MoreCatalogsSearchActor, Internal, 267
OrderConfirmationActor, External, 154
OrderConfirmationActor, Internal, 247
OrderLookupActor, External, 148
OrderNoteActor, Internal, 249
OrderSearchTreeQueryActor, Internal, 239
OriginalOrderNoteActor, Internal, 250
PaymentGroupActor, External, 135
PaymentGroupActor, Internal, 228
PriceListSearchActor, Internal, 271
PricingActor, External, 146
PricingActor, Internal, 269
ProductCatalogActor, External, 142
ProductCatalogActor, Internal, 265
ProfileActor, External, 116
PromotionsSearchActor, Internal, 276
PromotionWalletActor, Internal, 272
QuoteActor, Internal, 250
RespondEmailActor, Internal, 304
RestoreDefaultAgentOptionsActor, Internal, 181
ReturnsActor, External, 155
SaveOrderActor, External, 149
ScheduledOrderLookupActor, Internal, 260
ScheduledOrderTableActor, Internal, 262
SendAndCloseTicketActor, Internal, 306
ServiceCustomerProfileActor, Internal, 237, 286
ServiceUIProfileActor, Internal, 200
SessionConfirmationActor, External, 116
SessionConfirmationActor, Internal, 178
ShippingGroupActor, External, 129
ShippingGroupActor, Internal, 222
ShoppingCartActor, External, 121
ShoppingCartActor, Internal, 213
SiteGroupsActor, Internal, 308

401

StartNewCallActor, Internal, 181

StateListActor, External, 175
StoreLocatorActor, External, 174
StoreLocatorActor, Internal, 289
SubmitModifiedOrderActor, Internal, 248
TicketActor, Internal, 184
TicketingActor, Internal, 183
TicketLookupActor, Internal, 194
TicketSearchActor, Internal, 198
TicketStatusDescriptionActor, Internal, 200
UpdateCreditCardActor, External, 141, 162
UpdateCreditCardActor, Internal, 235, 302
UpdateHardgoodShippingGroupActor, External, 134
UpdateHardgoodShippingGroupActor, Internal, 227
ViewAllPendingApprovalsActor, Internal, 289
ViewOrderActor, Internal, 241
actor-chains, 71
registering, 69
actors, 71
execution order, 94
passing params, 83
types, 72
AddressBookActor, 207
AddStoreCreditActor, 277
Apache Axis, 35
ATGWS.dll, 45
installing, 46
AvailablePricedShippingMethodsActor
Internal, 226
AvailableShippingMethodsActor
External, 133

Internal, 245
CouponActor
External, 150
Internal, 232
CreateCreditCardActor
External, 140
Internal, 233
CreateHardgoodShippingGroupActor
External, 133
Internal, 226
CreditCardActor, 210
CSRCrossSellActor, 243
CSRGiftlistActor, 279
CSRGiftlistSearchActor, 286
CSRReturnsActor, 292
CSRScheduledOrderActor, 251
CSRScheduledOrderConfirmationActor, 258
CSRScheduledOrderInfoActor, 257
cURL, 59
command components, 61
CustomerProfileActor, 201
CustomerSearchTreeQueryActor, 204

EndCallActor, 182
Endeca Search, 146, 267
EnvironmentChangeActor, 268

CancelOrderActor
External, 149
Internal, 242
CartModifierActor
External, 124
Internal, 216
catalog search, 146
ChangeCurrentCustomerActor, 206
ChangeOrderActor, 241
ChangePasswordActor, 180
ChangeSiteActor, 309
ClosenessQualifierActor
External, 154
Internal, 276
CommitOrderActor
External, 153
Internal, 244
ConfirmLogoutActor, 180
ConfirmOrderActor
External, 150

402

D
DeactivateScheduleActor, 256
DefaultLoginPageActor, 181
DuplicateAndSubmitActor , 255
DuplicateOrderActor, 249
dynSessConf, 70, 81, 87

F
filters
bean classes, in REST MVC, 101
defining in REST MVC, 102
Legacy REST, 362
modifying in REST MVC, 109
repository items, in REST MVC, 101

G
GiftlistActor, 164
GiftlistLookupActor
External, 169
Internal, 285
GiftlistSearchActor, 172
GiftListTableActor, 288
GlobalInfoActor, 307

Index

H
HTTP
requests, 57, 61
requests in Legacy REST, 317, 331
status codes, 57, 341

I
IsScheduledOrderTemplateActor, 260

J
JAX-RPC, 4, 9, 11
and WSDL, 8
JMS Messages, 16
Patch Bay, 16
type, 16
JSON
output in Legacy REST, 331
output in MVC REST, 58

L
LostPromotionsActor
External, 163
Internal, 278

M
ManualAdjustmentsActor, 263
message sink, 18
MessageToolsActor, 310
methods
executing with Legacy REST, 317
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, 248
ModifyRefundValuesActor, 303
MoreCatalogsSearchActor, 267

O
OrderConfirmationActor
External, 154
Internal, 247
OrderLookupActor, 148
OrderNoteActor, 249
OrderSearchTreeQueryActor, 239
OriginalOrderNoteActor, 250

P
Patch Bay, 15, 17

Index

PaymentGroupActor
External, 135
Internal, 228
PriceListSearchActor, 271
PricingActor
External, 146
Internal, 269
ProductCatalogActor
External, 142
Internal, 265
ProfileActor, 116
PromotionsSearchActor, 276
PromotionWalletActor, 272
pushSite, 116

Q
QuoteActor, 250

R
repository
data binding Web Services, 21
delete item, 34
filtering in REST MVC, 108
items from XML, 29
items in Legacy REST, 354
match properties, 33
modify item, 32
RespondEmailActor, 304
REST, 55
cURL examples, 59
HTTP status codes, 57
output, 58
URLs, 56
URLs, adding parameters, 64
REST Legacy, 317
cURL example, 60
filtering, 362
framework, 56, 315
HTTP requests, 317
HTTP status codes, 341
output, default, 331
output, JSON, 332
output, XML, 332
repositories and, 354
security, 375
URLs, 317
URLs, adding parameters, 323
REST MVC, 67
cURL example, 60
examples, external user, 115
examples, internal users, 177
executing methods, 77
filtering, 101

403

framework, 56, 71
installing, 69
registering services, 69
schema, 73
security, 110
URLs, 73
URLS, error and success, 86
RestoreDefaultAgentOptionsActor, 181
ReturnsActor, 155

S
SaveOrderActor, 149
Scenario Actions, 16
Scenario Manager, 18
ScheduledOrderLookupActor, 260
ScheduledOrderTableActor, 262
security
Legacy REST, 375
REST MVC, 110
Web Services, 12
SendAndCloseTicketActor, 306
Service Endpoint Interface (SEI), 8
mapping to WSDL, 11
ServiceCustomerProfileActor, 237, 286
ServiceUIProfileActor, 200
servlet beans
filtering in REST MVC, 103
in Legacy REST, 353
retrieving in REST MVC, 84
session confirmation number, 70, 116, 178
disabing in Form actors, 87
disabling in Component actor, 81
SessionConfirmationActor
External, 116
Internal, 178
ShippingGroupActor
External, 129
Internal, 222
ShoppingCartActor
External, 121
Internal, 213
site context, external, 116
SiteGroupsActor, 308
SOAP, 4, 8, 9
and WSDL, 8
StartNewCallActor, 181
StateListActor, 175
StoreLocatorActor
External, 174
Internal, 289
SubmitModifiedOrderActor, 248

404

T
TicketActor, 184
TicketingActor, 183
TicketLookupActor, 194
TicketSearchActor, 198
TicketStatusDescriptionActor, 200

U
UpdateCreditCardActor
External, 141, 162
Internal, 235, 302
UpdateHardgoodShippingGroupActor
External, 134
Internal, 227
URLs, 56
adding Legacy REST parameters, 323
adding REST parameters, 64
and WSDL, 9
control parameters, 62
forwarding in REST MVC, 86
Legacy REST, 317
REST MVC, 73
success and error in REST MVC, 86

V
ViewAllPendingApprovalsActor, 289
ViewOrderActor, 241

W
Web 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

Index

security, 4, 12
serializer in .Net, 45, 49
serializer in Java, 36, 42
session sharing, 36, 45
static, 39, 39
wizard, 5
WSDL, 8, 10
XML file, 9
Web Services Description Language (WSDL) (see Also Web
Services)
mapping to SEI, 11
WebServicesGenerator, 6

X
XML
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, 332
output, REST, 58
repository items, 29
schema mapping, 42
schemas, 27
validating, 32

Index

405

406

Index