ATG Web Services Guide - product version: 10 · Version 10.2 ATG Web Services Guide Oracle ATG One...

Version 10.2

ATG Web Services Guide

Oracle ATG

One Main Street

Cambridge, MA 02142

USA

ATG Web Services Guide

Product version: 10.2

Release date: 04-30-13

Document identifier: WebServicesGuide1403311801

Copyright © 1997, 2013 Oracle and/or its affiliates. All rights reserved.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

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.

Portions of this product may contain the following: EditLive Authoring Software Copyright © 2004 Ephox Corporation. All rights reserved.

Some code licensed from RSA Security, Inc. Some portions licensed from IBM, which are available at http://oss.software.ibm.com/icu4j/.

This product may include software developed by the Apache Software Foundation (http://www.apache.org/). Spell checking software from

Wintertree Software Inc. The Sentry Spell Checker Engine © 2000 Wintertree Software Inc. This product also includes software developed

by the following: Free Software Foundation, GNU Operating System, Incanto, JSON.org, JODA.org, The Dojo Foundation, Adobe Systems

Incorporated, Eclipse Foundation and Singular Systems.

The software is based in part on the work of the Independent JPEG 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.

The MIT License

Copyright (c) 2007 FlexLib Contributors. See: http://code.google.com/p/flexlib/wiki/ProjectContributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the

"Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute,

sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following

conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS

OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR

OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ATG Web Services Guide v

Table of Contents

1. Creating and Using Web Services in the ATG Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

ATG 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 ATG Web Services from Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

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

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

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

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

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

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

About Web Services in the ATG Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

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

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

Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems . . . . . . . . . . . . . . . . . 49

2. Introduction to REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

REST Web Services Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

REST Web Services URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

HTTP Request Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Returning Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Using cURL for Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Writing cURL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

cURL Command Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Adding Control Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Functional Parameters for ATG REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Using Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Using URL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Using Message Body Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Input Values in ATG REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

I. ATG REST MVC Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

vi ATG Web Services Guide

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

Installing the REST MVC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Enabling REST Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Using Dynamo Session Confirmation Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

4. The REST MVC Definition Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

REST MVC Service Flow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Actor Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Request URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

XML Definition Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

The Actor-Template Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

The Actor-Chain Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

The Actor Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

The Component Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

The Droplet Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

The Form Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

The JSP Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

The Output Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

The Input Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

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

The Set Variable Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Actor XML Definition File Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Working with Implicit Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Combining Actor Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Bean Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

The Bean Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

The Filter Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

The Property Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

The Attribute Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

The Repository Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

The Item-Descriptor Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Working with Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

REST MVC Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Example: External User Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Example: Internal User Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Creating a New REST Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

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

External Service Call Workflow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Getting the Session Confirmation Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Working with Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Logging In Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Logging Out Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Creating New Customer Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Editing or Updating a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Viewing the Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Working with the Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

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

Adding Items to a Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

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

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

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

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

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

ATG Web Services Guide vii

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

Continuing the Checkout Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Working with the Shipping Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Displaying Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Specifying the Default Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Applying the Default Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Obtaining the Current Shipping Info List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Applying Shipping Groups and Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

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

Displaying Available Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Creating a New Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Editing a Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Working with the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Display the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Specifying the Default Payment Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Applying Default Payment Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Obtaining Current Payment Info Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

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

Creating a New Credit Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Updating a Credit Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Working with Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

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

Browsing the Catalog By Category ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Browsing the Catalog By Product ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Searching a Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Getting Product Prices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

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

Getting List Price and Sale Prices for a Product by SKU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Working with Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

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

Cancelling or Deleting an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Saving an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Claiming a Coupon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Confirming an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Committing an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Sending Order Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Working with Gift Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Creating a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Updating a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Adding Items to a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Adding Items to a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Removing Items from a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Removing Items from a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

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

Deleting a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

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

Viewing a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

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

Viewing a Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Searching for a Gift List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Working with In-Store Pickup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Searching for a Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

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

viii ATG Web Services Guide

Identifying a State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

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

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

Getting the Session Confirmation Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Logging Agents In and Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Logging In Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Logging Out Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Working with Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Starting a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Ending a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Adding a Call Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Viewing a Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Working with Customer Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Creating a New Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Updating an Existing Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Adding a Note to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Searching for a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Clearing a Customer Search Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Selecting a Customer to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Working with Customer Profile Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Changing the SKU of an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Assisting the Customer with the Shipping Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Displaying Available Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Specifying a Single Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Specifying Multiple Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Splitting Items into Different Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Applying Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Displaying All Available Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Creating New Hardgood Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Editing a Hardgood Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

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

Assisting the Customer with the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

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

ATG Web Services Guide ix

Getting Available Payment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

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

Claiming a Customer’s Coupon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Applying Multiple Payment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

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

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

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

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

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

Assisting Customers with Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

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

Viewing the Customer Order History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

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

Finding an Order by Order ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Selecting an Order to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Cancelling or Deleting the Current Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

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

Saving or Persisting an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Committing a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Confirming a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

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

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

Adjusting Customer’s Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Adjusting a Customer’s Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

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

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

Assisting Customers with Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

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

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

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

Search a Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Obtaining Global Session Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Listing Available Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Selecting a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Viewing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

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

II. Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

7. Using Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

x ATG Web Services Guide

HTTP Requests for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Nucleus Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Handling POST Requests as Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Logging In as an External User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Logging In as an Internal User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Functional Parameters for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Legacy REST Input Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Returned Data in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Choosing Output Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

JSON Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

XML Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Identifying a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Multiple Values in Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Return Depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Date Format in Returned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Errors and Exceptions in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Problems Performing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Problems Processing a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Working with Legacy REST Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Getting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Setting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Invoking Legacy REST Component Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Invoking Legacy REST Form Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Submitting Legacy REST Form Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Returning Legacy REST Form Handler Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Returning Legacy REST Form Handler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Legacy REST Form Value Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

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

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

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

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

Example Legacy REST Web Services JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Working with Repositories in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Listing Repository Items in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

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

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

Performing RQL Queries in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

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

Transient Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

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

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

Property Filtering with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Default Filtering in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Filtering Templates with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

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

Property Aliasing with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Suppressing Property Expansion in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Filtering Priority in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

ATG Web Services Guide xi

Configuring the Legacy REST Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

/atg/rest/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

/atg/rest/processor/BeanProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

/atg/rest/output/JSONOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

/atg/rest/output/XMLOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

/atg/rest/processor/RepositoryProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

/atg/rest/processor/RestSecurityProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Security for Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Legacy REST Security Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Quick Setup for Testing Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Global Security with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Component Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

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

Repository Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

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

8. Legacy Rest Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Java Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Creating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Creating a RestSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Starting a REST Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

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

Starting a Session Without Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Accessing Data from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

Creating a Raw REST Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Handling Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

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

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

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

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

ActionScript Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

atg.rest.client.RestComponentHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

atg.rest.client.RestRepositoryHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Calling Methods with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Formatting Input with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

xii ATG Web Services Guide

1 Creating and Using Web Services in the ATG Platform 1

1 Creating and Using Web Services in

the ATG Platform

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 ATG Web Commerce

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

an existing employee changes his or her marital status, you need to create or modify the employee’s profile in

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

changes automatically propagate to the other application.

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

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

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

is modified.

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

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

Commerce 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 ATG Web Commerce platform packages Web Services as: J2EE applications, in accordance with the

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

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

about these specifications, see the Java Community Process web site at:

http://www.jcp.org

The following sections discuss how to create Web Services in the Oracle ATG Web 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 ATG Web Services from Java Clients (page 35)

Accessing ATG Web Services from .NET Clients (page 44)

2 1 Creating and Using Web Services in the ATG Platform

ATG Web Services

In addition to any Web Services you create, the Oracle ATG Web 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 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 ATG 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 ATG Personalization Programming Guide.


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

ATG Commerce Programming Guide.



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


Creating Custom Web Services

The Oracle ATG Web Commerce platform provides infrastructure and tools that enable you to expose a wide

range of Oracle ATG Web Commerce functionality as Web Services. There are three kinds of Web Services you

can create that expose Oracle ATG Web Commerce functionality:

• 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 ATG Web 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 ATG Web Commerce platform uses Oracle’s reference

implementation of JAX-RPC. Parts of this reference implementation are used to generate Web Services, and

other parts of it handle the processing of SOAP messages when a Web Service is called.

Automatic Generation of Web Services

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

must create and package. The Oracle ATG Web 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.


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

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

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

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

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

Web Services from .NET Clients (page 44) section.

Method Limitations

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

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

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

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

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

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

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

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

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

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

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

method’s class (if it is a class provided by Oracle ATG Web Commerce) 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


• 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


• 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


• 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 ATG Web 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 ATG Web Commerce platform

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

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

Web Commerce platform Web Service Registry. The Web Service Registry is discussed in the Managing Web

Services (page 14) section.

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

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

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

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

WSDL Document

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

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

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

generated by the Oracle ATG Web Commerce platform always describes one method, because each Web Service

can expose only one Nucleus method.)

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

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

This document is used for two key purposes:

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

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

the service

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

document. For example:

<message name="getOrderStatusInput">


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

On the Oracle ATG Web 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>


<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 ATG Web Commerce platform,

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

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

to this:

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

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

designates the class that JAXRPCServlet dispatches the SOAP request to.

Handling Imported WSDL Documents in web.xml

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

These resources are declared in the web.xml file:

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

directory that has subdirectories holding WSDL documents

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

mapped to each path that will lead to a WSDL document

For example:

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


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


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

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

Security Components

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

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

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

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

See NucleusSecurityManager (page 12)

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

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

NucleusSecurityManager. See NucleusSecurityRepository (page 13)

NucleusSecurityManager

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

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

name and the SecurityPolicy component and ACL associated with it.

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

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

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

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

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

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

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

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

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

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


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 ATG Web 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 ATG 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 <ATG10dir>/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:


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 ATG Web 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 Commerce Web Services, specify the DCS.WebServices

module when you assemble your application.

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

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

Managing Web Services

The Dynamo Administration 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 Administration 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 ATG Commerce are running on your Dynamo server, the top of

the page will look similar to this:

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

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

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


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 ATG Web Commerce platform enables you to

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


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

Web 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 ATG Platform Programming Guide.

Using the JMS Message Web Service Wizard

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

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

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

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

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

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

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

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

standard ports where the Scenario Manager listens for scenario events.

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

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

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

SendPageVisitSEIImpl.

Structure of a JMS Web Service

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

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

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

Bay.

The receiveObjectMessage() method takes three parameters:

• The message object

• A String indicating the JMSType of the message

• A String indicating the Patch Bay port name to use

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

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

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

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

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

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


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 ATG

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


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 ATG Dynamo Administration 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 ATG Dynamo Administration 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


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


• 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


method argument for the property value. Since Web Services does not allow java.lang.Object as an input

(or output), this method cannot be used as a Web Service in this form. However, we can restrict the type of this

argument using the code generator template functionality, so when the Web Service is generated, the outward-

facing method will be strongly typed based on the property being set, and can simply call through to the more

generic setPropertyValue method in the body of the Web Service. The RepositoryService class has the

following properties:

Property Name Type Description

transaction

Manager

javax.transaction.

TransactionManager

The service that manages any transactions that are

used to execute repository methods on this instance.

mappingManager atg.repository.xml.

ItemDescriptor

MappingManager

The component that manages mapping files

based on repository and item descriptor name

combinations. For any methods that return a

RepositoryItem, this service will be consulted to

retrieve mapping files to use when transforming

these items into XML. See the Mapping Files

and XML Schemas (page 22) section for

more information abut mapping files and the

ItemDescriptorMappingManager class.

xmlGetService atg.repository.xml.

GetService

The service that knows how to turn

RepositoryItems into XML.

xmlAddService atg.repository.xml.

AddService

The service that knows how to add

RepositoryItems in XML format to a repository.

xmlUpdateService atg.repository.xml.

UpdateService

The service that knows how to take

RepositoryItems in XML format and update them

in their corresponding repositories.

For information about the XML service properties, see the Repository Operations (page 29) section.

Repository to XML Data Binding

One of the key aspects of integrating the Oracle ATG Web 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 ATG Web 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 ATG Web Commerce 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.


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 ATG 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 ATG Web Commerce platform and a remote system, you will

typically want to exclude certain data. For example, the Oracle ATG Web Commerce platform 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.


The following is the Document Type Definition (DTD) for mapping files:





<!ELEMENT item-descriptor (property*)>

<!ATTLIST item-descriptor repository-path CDATA #IMPLIED name CDATA #IMPLIED default-include (true | false) #IMPLIED>

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


name="user" default-include="true"> <property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property> <property name="slotInstances" include="false"/> <property name="scenarioInstances" include="false"/> <property name="mailings" include="false"/> <property name="scenarioValues" include="false"/> <property name="firstName" targetName="first_name"/></item-descriptor>

The data binding services all work with a single item descriptor and its properties (including any other item

descriptors that are properties of the main item descriptor). The mapping file uses the item-descriptor tag to

specify the repository and item descriptor that the mapping file is associated with:

<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true">

The default-include attribute specifies whether the item’s properties should be included or excluded by

default. This value can be overridden for individual properties. In this mapping file, various scenario-related

properties are excluded:

<property name="slotInstances" include="false"/><property name="scenarioInstances" include="false"/><property name="mailings" include="false"/><property name="scenarioValues" include="false"/>

If a property is an item descriptor, there must be an item-descriptor tag inside the property tag. For

example, the homeAddress property points to a contactInfo item descriptor:

<property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property>

Note that the item-descriptor tag for contactInfo can have property tags within it. The nesting

of property tags and item-descriptor tags must reflect the hierarchy of the item descriptors in the

repository. If you do not include a property tag for a property that points to an item descriptor (such as the

homeAddress property shown above), the Oracle ATG Web 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:


<property name="firstName" targetName="first_name"/>

Managing Mapping Files for Repository Item Descriptors

The Oracle ATG Web Commerce platform includes two classes that help identify the appropriate mapping file for

each item descriptor that you want to use with the repository2xml data binding facility. These classes are used

by Web Service clients:

atg.repository.xml.ItemDescriptorMappingatg.repository.xml.ItemDescriptorMappingManager

ItemDescriptorMapping

An ItemDescriptorMapping is a simple bean that holds information about relationships between repository

item descriptors and mapping files. The mapping files describe what properties are to be exposed when

an item from that item descriptor is to be transformed into XML. Each ItemDescriptorMapping pertains

to exactly one repository: for example, you would have a UserProfileItemDescriptorMapping, or a

PromotionItemDescriptorMapping component, each of which would provide a list of item descriptor names

from the corresponding repository and their corresponding mapping files.

An ItemDescriptorMapping contains only three properties:


repositoryPath java.lang.String The path to the repository supported by this

ItemDescriptorMapping. This is a read-only

property

repository atg.repository.

Repository

The path to the repository supported by

this ItemDescriptorMapping. Similar to

repositoryPath but this property will

resolve to an actual Repository instance, and

is writeable.

itemDescriptorMapping java.util.Map A map where the keys are item descriptor

names and the values are locations of

mapping files, relative to the configuration

path, which provide rules for how an item of

the keyed item descriptor name appears in

XML format

Here is an example properties file for an ItemDescriptorMapping that supports the profile repository:

$class=atg.repository.xml.ItemDescriptorMappingrepository=/atg/userprofiling/ProfileAdapterRepositoryitemDescriptorMapping=\ user=/atg/userprofiling/userMapping.xml,\ contactInfo=/atg/userprofiling/contactInfoMapping.xml


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


itemDescriptorMappings atg.repository.xml.

ItemDescriptor

Mapping[]

An array of ItemDescriptorMapping

components. When a user calls methods to

retrieve mapping files, this component sifts

through the itemDescriptorMappings to

determine the correct mapping.

Here is an example properties file:

$class=atg.repository.xml.ItemDescriptorMappingManageritemDescriptorMappings=\ /atg/userprofiling/UserProfileItemMapping,\ /atg/userprofiling/ContactInfoItemMapping

The following ItemDescriptorMappingManager methods can be used to retrieve mapping files:

getMappingFileName(String pRepositoryPath, String pItemDescriptorName)

Using the given repository path and item descriptor name, returns the mapping file for that given path:name

combination, or null if none exists.

getMappingFileName(Repository pRepository, String pItemDescriptorName)

Using the given repository and item descriptor name, returns the mapping file for that given repository:name

combination, or null if none exists.


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 ATG Web 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 ATG Web 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 <ATG10dir>/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):


generateXMLSchema -m DSSJ2EEDemo –repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user

The generated XML Schema is saved by the Schema Manager specified by the schemaManager property

of the Schema Generator component. The default Schema Generator is the /atg/repository/xml/

SchemaGenerator component, and its schemaManager property points by default to the /atg/repository/

xml/SchemaManager component. Note that if the user item descriptor contains other item descriptors as

properties, the generated Schema will reflect these other item descriptors as well.

To save the Schema to the current working directory in addition to the directory determined by the

XMLSchemaFileDirectory property of the Schema Manager:

generateXMLSchema -m DSSJ2EEDemo –repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -outputDirectory .

Managing Schemas and Mapping Files

As mentioned above, the default Schema Generator has a schemaManager property that points to the

/atg/repository/xml/SchemaManager component. In addition, each of the data binding service

components (described below) has an XMLSchemaManager property that points to this SchemaManager

component. This component is of class atg.repository.xml.XMLSchemaManager. This class, which extends

atg.repository.databinding.MappingManager, manages XML Schemas and mapping files. For example,

this class has mappingFileDirectories and XMLSchemaFileDirectory properties that specify the

directories where mapping files and Schemas are stored. Note that Schemas must have the extension .xsd and

mapping files must have the extension .xml.

For example, suppose you want to generate an XML Schema and specify a mapping file to use. The command

would look something like this:

generateXMLSchema -m DSSJ2EEDemo –repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -mappingFile profileMapping.xml

Notice that only the name of the mapping file is specified, not the entire pathname. The Schema Manager’s

mappingFileDirectories property points to the directories where the mapping file should be stored.

PropertyElementNameSeparator

The repository2xml feature specifies a separator character, which functions to separate a property name

from the name of its item descriptor. By default, this separator character is . (dot). The default separator

character may not work for you if, for example, you use composite repository IDs that also use the . (dot)

character to separate elements of the repository ID. You can specify a different separator character in the

propertyElementNameSeparator property of the /atg/repository/xml/RepositoryXMLTools

component.

Item References

In a repository schema, a map, set, list, or array property can point to a single other item using the itemRef

attribute. The value assigned to the itemRef attribute concatenates the item descriptor name, the property

element separator, and the repository ID. In the following example, the item descriptor name is role, the

property element separator is . (dot) and the repository ID is 2900004:


<user:itemRef itemRef="role.2900004"/>

The following is a more extended example, showing the context for the itemRef attribute:

<user:user xmlns:user=http://www.atg.com/ns/profileMapping/UserProfiles/user xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd " ID="user747"> <user:homeAddress itemRef="contactInfo.1040001"/> <user:roles> <user:itemRef itemRef="role.2900004"/> <user:itemRef itemRef="role.3000008"/> </user:roles></user:user>

Repository Operations

The atg.repository.xml package includes a service class for each of the four repository operations

supported by the data binding facility. The following table lists these classes and the Nucleus instances included

in Dynamo:

Class Nucleus component

atg.repository.xml.GetService /atg/repository/xml/GetService

atg.repository.xml.AddService /atg/repository/xml/AddService

atg.repository.xml.UpdateService /atg/repository/xml/UpdateService

atg.repository.xml.RemoveService /atg/repository/xml/RemoveService

The following sections discuss each of these classes and the operations they perform. See the entries for these

classes in the ATG Platform API Reference for more information.

Getting Repository Items

You use getItemAsXML() method of the atg.repository.xml.GetService class to create XML documents

from repository items. This method takes a repository item as an input argument and returns a String

containing an XML representation of this item. If you write out this String (e.g., to a file), be sure to use the

same character encoding that the repository uses.

Some versions of the getItemAsXML() method take additional inputs for specifying a String array of the

names of the properties to write out or a String containing the name of the mapping file to use. If you

supply only a repository item as input, the method uses the default inclusion rules (described in the Mapping

Files (page 22) section) to determine which properties to include.

By default, GetService writes out an XML document as a single line, because it is intended to be machine-

readable. If you want the generated XML to be human-readable, set the indentXMLOutput property of the

GetService component to true. The resulting XML will have appropriate line breaks.


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>[email protected]</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>


<user:guests>false</user:guests> <user:brokers>false</user:brokers> <user:investors>true</user:investors></user:user>

Notice that information about the XML Schema for this data is included in the user:user tag at the beginning

of the document:

xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd "

The xsi:schemaLocation attribute specifies the URL and name of the Schema file. The Schema

filename (profileMapping+UserProfiles+user.xsd) is determined by the name of the mapping file

(profileMapping.xml), the name of the repository (UserProfiles), and the item descriptor (user). If no

mapping file is used to create the document, the Schema filename indicates the repository and item descriptor.

If you want the Schema filename to include the entire pathname, set the appendRelativeSchemaLocation

property of the GetService component to true. This is especially important if you’re using an external Schema

verification tool, which will generally need the complete pathname to find the Schema file.

If you use a mapping file when you create an instance document, you should be sure to supply the name of this

mapping file to the generateXMLSchema command (using the –mappingFile argument) when you generate

the Schema. Otherwise the actual Schema filename will not match the name in the xsi:schemaLocation

tag, and the Schema may not accurately reflect the data in the instance document; as a result, you may not

be able to validate the data when reading it into a remote system (or reading it back into Dynamo using

AddService). Note also that if your call to getItemAsXML() includes an input argument that specifies the

names of properties to write out, the Schema will not accurately reflect the data in the instance document, so

validation will not be possible.

To avoid any conflict between tag names, the XML tags in the generated instance document are named

using the convention itemType:propertyName; for example the user:userType tag stores the value

of the userType property of the user item type. If the addItemTypeToPropertyNames property of the

RepositoryXMLTools component that GetService points to is set to true, the tags are named using the

convention itemType:itemType.propertyName; in this case, the tag name would be user:user.userType.

By default addItemTypeToPropertyNames is set to true, because the resulting XML is less likely to result in

naming collisions.

Adding Repository Items

You use the addItem() method of the atg.repository.xml.AddService class to create new

repository items from XML documents. This method takes an XML document as an input argument and

returns a repository item. The XML document can be in the form of a String, a java.io.Reader, or a

java.io.InputStream. The method examines the schemaLocation attribute in the XML document to

determine if there is a mapping file associated with the document. Some versions of the method take additional

arguments for specifying how to handle missing or empty tags, and whether the data should be validated

against a Schema.

For some examples of how a repository item might look in XML document form, see the <ATG10dir>/

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

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


Validating Repository Item Data

The addItem() method can optionally validate the data in an XML instance document against the Schema

specified in the instance document. Validation is enabled or disabled by the validate property of the

AddService component. By default, this property is set to false, because validation slows down processing of

the document. To enable validation, set the validate property to true.

The addItem() method can also take a Boolean argument to specify whether to validate the document. The

value of this argument overrides the validate property. If you do not specify this argument, addItem() uses

the validate property to determine whether to validate the document.

If you are confident that your data is valid, you can disable validation, and the instance document will be

processed more quickly. However, if the data turns out to be invalid, the invalid data may be written to the

repository. If you enable validation and the data is invalid, addItem() does not write the contents of the

instance document to the repository.

Updating Repository Items

You use the updateItem() method of the atg.repository.xml.UpdateService class to modify a

repository item. For example, the following instance document updates a user’s email address:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.emailAddress>[email protected]</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>[email protected]</user:user.emailAddress> <user:user.login>sandy</user:user.login></user:user>


The application would then use the following code to update the user repository item whose login value is

sandy (assuming the inputXML String contains the instance document shown above):

String[] matchProperties = {"login"};RepositoryItem updatedItem = UpdateService.updateItem(inputXML, matchProperties);

Note that UpdateService determines the repository and item type from the namespace of the instance

document. See Getting Repository Items (page 29).

The matchProperties array can contain any number of property names. If the value of each repository item

property named in matchProperties matches its corresponding attribute in the XML instance document, the

item is selected for update. All of the specified properties must match for the item to be selected; for example, if

matchProperties lists login and lastName properties, the values of both properties must match. If multiple

items are selected, an exception is thrown and no update occurs.

Matching is limited to top-level properties of the repository item. Subproperties (such as properties of other

repository items) cannot be matched. So, for example, if a user item has a lastName property that is a String,

you can include lastName in matchProperties; but if a user item has a shippingAddress property that is

another repository item, you cannot include, say, shippingAddress.city in matchProperties.

If a property has been mapped to a different name in the instance document, the name to match on is the

property name used in the repository, not the instance document. For example, suppose you use a mapping file

to map a user item’s dateOfBirth property to the name birthday, like this:

<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true"> <property name="dateOfBirth" targetName="birthday"/>

The corresponding instance document might look like this:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.birthday>02-06-1975</user:user.birthday></user:user>

To specify this property in matchProperties, you use the name of the property as it is defined in the repository

(dateOfBirth), not the target name (birthday). For example:

String[] matchProperties = {"dateOfBirth"};

You can configure the UpdateService to add a repository item if an attempt to update does not find a match.

If you want the UpdateService to add items when no items are matched, set the addWhenNoMatchedItems

property of the UpdateService to true.

If the property being updated is a simple type (such as a String), then its value is updated by the

UpdateService. When the property being updated is a list, map or array, then the old value is replaced by the

new value. The new value is not appended to the old value. If the property being updated is an item descriptor,

then the appropriate fields of the existing item descriptors are updated.


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>[email protected]</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.


Accessing ATG Web Services from Java Clients

The Oracle ATG Web Commerce platform permits external Java clients to access Nucleus methods by exposing

them as Oracle ATG Web Commerce Web Services. Many such Oracle ATG Web Commerce Web Services are

included with the Oracle ATG Web Commerce platform, as are tools for creating custom Web Services. For a list

of Oracle ATG Web Commerce Web Services, see ATG 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 ATG Web

Commerce platform, and routed to the Nucleus method itself. Other Oracle ATG Web Commerce resources, such

as JMS messages and RepositoryItems, can also be exposed as Oracle ATG Web Commerce Web Services.

The Oracle ATG Web Commerce 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 Oracle ATG Web Commerce Web Services from an Axis client. Rather

than provide a broad discussion on how to use Axis, this section describes Oracle ATG Web Commerce-specific

features and processes that you need to be familiar with. Please see the Axis documentation for comprehensive

instructions.

To access an Oracle ATG Web Commerce Web Service, you need to be familiar with the following topics:

About ATG Web Services (page 35)

Before You Begin Using a Java Client (page 36)

Writing a CookieContainer Class (page 37)

Calling ATG Web Services from a Java Client (page 39)

Creating a Serializer and Deserializer (page 42)

About ATG Web Services

For the most part, you call Oracle ATG Web Commerce Web Services in the same way you call Web Services

elsewhere. While the general process may not differ, it’s important that you are aware of these platform-specific

features.

Security

The content you see as a response to a Web Service call depends on your access privileges. When you login

using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent

Web Service calls in that session are associated with that identity and related role.

For more information on loginUser, see the ATG 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 ATG Repository Guide and the ATG 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.

Sharing Sessions




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 ATG Web Commerce systems. The following Web

Services transmit content that is natively stored as RepositoryItems:

• getProfile

• getRepositoryItem

• performRQLQuery

• getOrderAsXML (Commerce users only)

• getOrdersAsXML (Commerce users only)

• getProductXMLById (Commerce users only)

• getProductXMLByDescription (Commerce users only)

• getProductXMLByRQL (Commerce users only)

• getProductSkusXML (Commerce users only)

• getPromotionsAsXML (Commerce users only)

The Oracle ATG Web Commerce platform includes several tools for working with RepositoryItems. To make

a client able to serialize and deserialize RepositoryItems, you need to translate the RepositoryItem class

into a language that’s native to your client. See Creating a Serializer and Deserializer (page 42) for more

information.

Before You Begin Using a Java Client

Before you can access a Web Service, you need to make sure the Oracle ATG Web 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.

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 ATG Web Services from a Java

Client (page 39).) If you always make only one of these call types, your own CookieContainer class does

not need to handle both cases

package com.example.webservice;

import org.apache.axis.MessageContext;import org.apache.axis.client.Call;import org.apache.axis.client.Stub;import org.apache.axis.transport.http.HTTPConstants;

/** * A class that can be passed between web service clients that keeps track of * the cookies received from the server. These cookies are then used by * subsequent web service client calls in order to ensure that session * state is maintained.**/public class CookieContainer{ //------------------------------------- // Member variables //-------------------------------------

/** Array of cookies from the Set-Cookie HTTP header **/ private String[] mCookies = null;

/** Array of cookies from the Set-Cookie2 HTTP header **/ private String[] mCookies2 = null;

//------------------------------------- // Methods //-------------------------------------

/** * Gets the cookies set by the Set-Cookie HTTP header * @return the cookies from the Set-Cookie HTTP header, which * may be null **/ public String[] getCookies() { return mCookies; }


/** * Gets the cookies set by the Set-Cookie2 HTTP header * @return the cookies from the Set-Cookie2 HTTP header, which * may be null **/ 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); }}

Calling ATG Web Services from a Java Client

When you call a Web Service, you create resources that describe the Web Service you want to call, its location,

and initial inputs. Axis then takes those resources and produces from them a SOAP message that it then sends to

the Web Service itself.

There are two ways to create a Web Service call:

• Use a client stub to create a static Web Service call

• Use the Dynamic Invocation Interface to create a dynamic Web Service call

The main distinction between the two processes is the data types they can handle. Because using Web Services

requires that data be converted into several formats — from a native format into an XML representation of that

format back into the native form — it is important that you choose a process designed to work with the data

types accessed by the Web Services you want to employ.

The static process can handle any data type regardless of whether it’s primitive, complex, object, or non-

standard. Non-standard types may require some extra effort as is the case when accessing Oracle ATG Web

Commerce 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 Oracle ATG Web Commerce

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.

For example, to create a static call to the loginUser Web Service:

1. Create and compile the client stub, if one does not already exist for the Web Service. See Creating and

Compiling a Client Stub (page 40) below.

2. Add the client stub to the CLASSPATH variable so the client stub is available to local Web Services resources.

3. Create and compile the client. See Creating and Compiling a Client (page 40) below.

4. Use Axis to execute the Web Service call:

loginStub.createUser(pProfileAsXML)

The format of this call is:

clientStub.web_service(generated_web_Service_Call_instance)

Axis creates the XML message, wraps it in SOAP, and sends it via HTTP to the Web Service location in the client

stub.

See Creating and Compiling a Client Stub (page 40) and Creating and Compiling a Client (page 40).

Creating and Compiling a Client Stub

The client stub describes the Web Service method and supporting resources in a structure that’s familiar to the

client. Each Web Service requires a stub for each client that executes it. You can reuse a stub for subsequent calls

so you only need to create it once. However, simultaneous calls to a Web Service made by different threads will

require that a unique client stub instance exists for each thread.

To create and compile a client stub for the loginUser Web Service:

1. Locate the active WSDL file via HTTP for the Web Service you want to call. The URL is provided in with the

documentation that describes each Web Service:

• For Repository Web Services, see the ATG Repository Guide

• For Personalization Web Services, see the ATG Personalization Programming Guide

• For Commerce Web Services, see the ATG Commerce Programming Guide

It’s important that you access the runtime and not the static version of the WSDL document. Assuming

that you included the modules holding the Web Services you want to access when you assembled your

application, you should be able to download the runtime version of the WSDL.

2. Use the Axis WSDL-to-Java tool to generate the client stub based on the WSDL.

3. Compile the client stub.

Creating and Compiling a Client

A Web Service client is a Java file that describes precisely what the Web Service should do. It provides the actions

the Web Service should commit and initial values.


If you want to enable Web Services to share sessions, your code needs to pass cookies between calls.

The following example, which creates a static Web Service call to the loginUser Web Service, uses the

CookieContainer class shown in Writing a CookieContainer Class (page 37):

{ LoginUserSEIService loginService = new LoginUserSEIServiceLocator(); LoginUserSEI loginStub = loginService.getLoginUserSEIPort(); org.apache.axis.client.Stub axisStub = (org.apache.axis.client.Stub) loginStub; CookieContainer cookieContainer = new CookieContainer();

axisStub.setMaintainSession(true); // Don't allow XML elements to reference other XML elements axisStub._setPropertyValue(AxisEngine.PROP_DOMULTIREFS, new Boolean(false)); // Push cookies onto the Stub cookieContainer.pushCookies(stub);

String userId = loginStub.loginUser("bhavern", " xyo8bnif", false);

// Get cookies out of the Stub, and pass them to subsequent calls as needed cookieContainer.extractCookies(stub);}

Creating a Call Using the Dynamic Invocation Interface (Dynamic)

A dynamic Web Service call holds all relevant information in one file, the client, which Axis converts directly into

the SOAP message. Essentially, the client you create is a Java version of the call itself, excluding some relative

values that are replaced with absolute ones at compile time.

Keep in mind that if you want to access a Web Service that uses non-standard data types, you need to create

your Web Service call following the static process. See Creating a Call Using a Client Stub (Static) (page 39).

If you want to enable Web Services to share sessions, your code needs to pass cookies between calls. The

following example, which creates a dynamic Web Service call to the loginUser Web Service, uses the

CookieContainer class shown in Writing a CookieContainer Class (page 37):

Service service = new Service();Call call = (Call) service.createCall();

// Get a hold of a CookieContainer passed to this method/classCookieContainer cookieContainer = new CookieContainer();

// Push previous cookies (if any) to the new Call objectcookieContainer.pushCookies(call);call.setMaintainSession(true);

call.setTargetEndpointAddress(newjava.net.URL("http://hostname:port/userprofiling/usersession/loginUser/loginUser") );

// Don't allow XML elements to reference other XML elementscall.setProperty(AxisEngine.PROP_DOMULTIREFS,Boolean.FALSE)

call.addParameter("Login", org.apache.axis.Constants.XSD_STRING, javax.xml.rpc.ParameterMode.IN);call.addParameter("Password", org.apache.axis.Constants.XSD_STRING,


javax.xml.rpc.ParameterMode.IN);call.addParameter("IsPasswordEncrypted", org.apache.axis.Constants.XSD_BOOLEAN, javax.xml.rpc.ParameterMode.IN);call.setReturnType(org.apache.axis.Constants.XSD_STRING);call.setOperationName(new QName("http://www.atg.com/webservices", "loginUser"));String userId = (String) call.invoke( new Object[] { "bhavern", "xyo8bnif", Boolean.FALSE } );

// Extract new cookies from the Call into the CookieContainer object,// which can then be passed to subsequent callscookieContainer.extractCookies(call);}

Creating a Serializer and Deserializer

When you want to use a Web Service that accesses RepositoryItems, you can create a mechanism for

translating foreign content into different formats:

• A serializer will convert content from a native format into XML that will eventually undergo another

conversion into a RepositoryItem. You need to create a serializer for “set” operations in which the client

sends content to the Web Service in the context of the call

• A deserializer constructs XML content that was originally formatted as RepositoryItems into a native

content format. You need to create a deserializer for “get” operations in which a Web call returns content that

represents a RepositoryItem

Both a serializer and a deserializer will need to understand the RepositoryItem schema. When you create

the XML schema and a mapping file, you need information about the Web Service itself. You can find that

information in the sections that describe the Web Service:

• For getProfile, see the ATG Personalization Programming Guide

• For getOrderAsXML, getOrdersAsXML, getProductXMLById, getProductXMLByDescription,

getProductXMLByRQL, getProductSkusXML, getPromotionAsXML, see the ATG Commerce Programming

Guide

• For Repository Web Services , see the ATG 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 43).

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

To create a mapping file, you need to know the properties defined by your item descriptor so you can decide

which of them ought to be represented in the XML schema. You can find the location of a Repository’s item

descriptor in the Oracle ATG Web Commerce platform Dynamo Administration UI:

1. In Dynamo Server Admin, click the Component Browser link.

2. Navigate to the Repository component that correlates to your Web Service as indicated in the documentation

for your Oracle ATG Web Commerce 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 ATG Web Commerce 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

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

your Oracle ATG Web Commerce Web Service.

You may find these two optional arguments helpful:

• outputDirectory copies the resultant XML schema to the directory of your choosing

• mappingFile specifies a file that describes the RepositoryItem properties to include in the resultant XML

schema

Other Required Schemas

When a client deserializes a RepositoryItem, it uses the schema derived from the item descriptor to

reconstruct each repository object and its properties in the appropriate data types. Depending on the makeup

of the item descriptor, you may need to also generate a schema for related item descriptors.

Consider the Profile repository that uses the user item descriptor. There are two item descriptors, broker

and investor, that are subtypes of user. If you were to use the updateProfile Web Service call while


the Relationship Management platform is running, user and all subtypes of it that are part of Relationship

Management are accessible. When you call updateProfile, it’s unclear which version of user you want to call:

user, investor or broker. In this case, you need to generate XML schemes for all three item descriptors.

In short, you need to generate an XML schema for all item descriptors used by RepositoryItems that are

accessed by a Web Service call and for any related (parent or child) item descriptors that are running when the

call is made.

It is difficult to supply a general list of all item descriptors for which this added step applies because the contents

of that list depend on many factors. When deciding if you need to create supplemental XML schemas for an item

descriptor, consider the following:

• The Web Service you are calling

• The modules running when you call that Web Service

• The contents of your Oracle ATG Web Commerce module stack

• The custom Oracle ATG Web Commerce 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 Consumer Commerce module. A second order item descriptor is supplied

by Business Commerce and, when both modules are running, the order item descriptors are concatenated so

that Business Commerce properties 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 ATG Web Services from .NET Clients

he Oracle ATG Web Commerce platform permits .NET clients to access Nucleus methods by exposing them as

Oracle ATG Web Commerce Web Services. Many such Oracle ATG Web Commerce Web Services are included

with the Oracle ATG Web Commerce platform as are tools for creating custom Web Services. For a list of Oracle

ATG Web Commerce Web Services, see ATG Web Services (page 2). .NET clients are able to contact those

Web Services through a carefully constructed call that’s built in .NET, translated into XML wrapped in SOAP,

transmitted to the Oracle ATG Web Commerce platform, and routed to the Nucleus method itself. Other Oracle

ATG Web Commerce resources, such as JMS messages and RepositoryItems can also be exposed as Oracle

ATG Web Commerce Web Services.

This section describes how to call Oracle ATG Web Commerce Web Services from a .NET client. Rather

than provide a broad discussion on how to use .NET, this section describes Oracle ATG Web Commerce-

specific features and processes that you need to be familiar with. Please see your .NET documentation for

comprehensive instructions.

To access an Oracle ATG Web Commerce Web Service, you need to be familiar with the following topics:

About Web Services in the ATG Platform (page 45)

Before You Begin Using a .NET Client (page 46)


Calling ATG Web Services from a .NET Client (page 47)

Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems (page

49)

About Web Services in the ATG Platform

For the most part, you call ATG Web Services in the same way you call Web Services elsewhere. While the general

process may not differ, it’s important that you are aware of these platform-specific features.

Security

The content you see as a response to a Web Service call depends on your access privileges. When you login

using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent

Web Service calls in that session are associated with that identity and related role.

For more information on loginUser, see the ATG 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 ATG Repository Guide and the ATG 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




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 ATG 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 ATG Web Commerce platform provides preconfigured client stubs for all Oracle ATG Web Commerce

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 Oracle ATG Web Commerce

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 Oracle ATG Web Commerce 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 ATG Web Commerce platform as

RepositoryItems. The following Web Services transmit content that is natively stored as RepositoryItems:

• getProfile

• getRepositoryItem

• performRQLQuery

• getOrderAsXML (Commerce users only)

• getOrdersAsXML (Commerce users only)

• getProductXMLById (Commerce users only)

• getProductXMLByDescription (Commerce users only)

• getProductXMLByRQL (Commerce users only)

• getProductSkusXML (Commerce users only)

• getPromotionsAsXML (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 to Serialize and Deserialize

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 ATG Web 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 Oracle ATG Web Commerce Web Service. It also

provides the Atg.DotNet.WebService API used for serializing and deserializing RepositoryItems. All users

who want to access Oracle ATG Web Commerce 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 <ATG10dir>/DAS/os_specific_files/i486-unknown-

win32/ATGWS.dll to your Windows\Assembly folder.

2. Open a command prompt and enter the following command:

<DotNetdir>:\ gacutil/i <ATG10dir>/DAS/os_specific_files/i486-unknown-

win32/ATGWS.dll

In this example, <DotNetdir> represents the parent directory, such as c:\DotNet that holds your .NET

software.

Keep in mind that each time you install a new version of ATGWS.dll, it coexists with older versions. The latest

version of ATGWS.dll will instruct the .NET client to use it. There’s no need to uninstall ATGWS.dll when you

want to install a new version. Remember when you do install new versions, you need to update references in

VS.NET to the old version of ATGWS.dll. If you’d like to remove all versions of ATGWS.dll, use this command in

a command prompt:

<DotNetdir> gacutil/u <ATG10dir>/DAS/os_specific_files/i486-unknown-win32/ATGWS

Calling ATG Web Services from a .NET Client

This section describes the components you need in order to call an Oracle ATG Web Commerce 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 ATG Web Commerce 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 an ATG Web Service (page 47)

Accessing a Custom ATG Web Service (page 48)

Sample Web Service Calls (page 48)

Accessing an ATG Web Service

The Oracle ATG Web Commerce platform provides client stubs for all Oracle ATG Web Commerce platform 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 ATG Web Service

To access a Web Service that you created in the Oracle ATG Web 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 Oracle ATG Web Commerce Web Services in the documentation for the specific Web

Service:

• For Repository Web Services, see the ATG Repository Guide

• For Personalization Web Services, see the ATG Personalization Programming Guide

• For Commerce Web Services, see the ATG Commerce Programming Guide

Sample Web Service Calls

The Web Service call is a document that incorporates calls to any number of Oracle ATG Web Commerce 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 Oracle ATG Web

Commerce Web Service.

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

http://example.com/repository/generic/getItem/getItem

http://example.com/repository/generic/getItem/getItem


other Web Services refer to. Because an instance of a CookieContainer is created in this code and assigned to

each Web Service stub, all Web Services called here exist in the same session.

For brevity these examples omit some details such as a exception handling for the SoapException as well as

class syntax.

using System.Net; // for CookieContainerusing Atg.DotNet.WebService.Repository.GetItem;using Atg.DotNet.WebService.Repository.PerformRQLQuery;using Atg.DotNet.WebService.UserSession.LoginUser;using Atg.DotNet.WebService.UserSession.LogoutUser;

// create stub instancesGetItemSEIService getItemClientStub = new GetItemSEIService();PerformRQLQuerySEIService performRQLQueryClientStub = newPerformRQLQuerySEIService();LoginUserSEIService loginUserClientStub = new LoginUserSEIService();LogoutUserSEIService logoutUserClientStub = new LogoutUserSEIService();

// create a new cookie container for our session and share it between// the various stub instancesCookieContainer cookieContainer = new CookieContainer();getItemClientStub.CookieContainer = cookieContainer;performRQLQueryClientStub.CookieContainer = cookieContainer;loginUserClientStub.CookieContainer = cookieContainer;logoutUserClientStub.CookieContainer = cookieContainer;

// authenticate the user for the sessionloginUserClientStub.loginUser("user", "password", false);

// call servicesstring itemXml = getItemClientStub.getItem("/nucleus/path/to/repository", "itemDescriptorName", "repositoryId");string[] itemsXml = performRQLQueryClientStub.performRQLQuery("/nucleus/path/to/repository", "itemDescriptorName", "property = 'value'");

// log out the userlogoutUserClientStub.logoutUser();

Using the Atg.DotNet.WebService API to Serialize and Deserialize 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 Oracle ATG Web Commerce 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 Oracle ATG Web Commerce and

custom Web Services that access RepositoryItems.

The Atg.DotNet.WebService is made up of the following classes:


RepositoryItem Class (page 51)

Property Class (page 52)

RepositoryItemRef Class (page 53)

Complex Type Class (page 53)

NoSuchPropertyException Class (page 54)

RepositoryItemSerializer Class (page 54)

RepositoryItemSerializationException Class (page 55)

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

Web Commerce Web Service resulting from your initial Web Service call. The response, formatted in XML, holds a

string object that represents Oracle ATG Web Commerce 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 ATG Web Commerce platform and the external system .NET

communicates with, is serialized. Once an item has been serialized, there’s parity across systems so all properties

on that item are marked as “clean.” You can alter the default dirty/clean designation in the following ways:

• Use the RepositoryItem.Dirty property to toggle an object’s clean/dirty status

• Use the RepositoryItem.setPropertyDirty() methods to toggle a property’s clean/dirty status

During deserialization, content that represents RepositoryItem properties is parsed based on a few rules. All

properties are converted back to the native data type, assuming that data type is available in .NET. The following

data types do not exist in .NET and so values for these types are converted as follows:

• Oracle ATG Web Commerce Map properties use Hashtable data type in .NET

• Oracle ATG Web Commerce Date or Timestamp properties are stored as .NET DateTime data type

• Oracle ATG Web Commerce Set properties are formatted as .NET Array data type

• Oracle ATG Web Commerce properties that refer to other Oracle ATG Web Commerce RepositoryItems

behave as .NET Hashtables

For the most part, Atg.DotNet.WebService determines format output type by relying on prior processing.

For example, if it had deserialized a particular RepositoryItem, such a Growth fund, then assuming no new


properties are added, when the Growth fund is serialized, Atg.DotNet.WebService.RepositoryItem is

aware of each property’s destination data type. However, in all other circumstances, you should explicitly include

the XML data type for the property. In short, under these circumstances include data types:

• The first time a RepositoryItem is serialized when it has not been previously deserialized, such as in the case

of adding a new item to the Oracle ATG Web 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 ATG Web Commerce platform atg/

repository/xml/RepositoryXMLTools component has the encodeRepositoryIdAsAttr property set to

true. This is the default setting.

RepositoryItem Class

The Atg.DotNet.WebService.RepositoryItem class is designed to manage XML serialization and

deserialization for easy interoperability with the .NET Web Services framework.

To serialize or deserialize a RepositoryItem, you need only to pass in the RepositoryName and

RepositoryId. When you are working with content for the first time, you also need to call setPropertyType

to instruct the deserializer/serializer to use a specific output data type.

Class Element Description

properties Dirty

Determines the overall dirtiness of an object by specifying whether all properties are

clean (false) or one of more properties are dirty (true).

ItemDescriptorName

Name of the item descriptor associated with the object’s RepositoryItem.

Properties

List of properties for this RepositoryItem.

RepositoryId

ID provided to the object’s RepositoryItem representation.

RepositoryName

Name of the repository that the RepositoryItem is part of.

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 ATG Web Commerce platform,

populating it with values parsed from the XML instance of the Web Service call. The XML

instance is a by-product from the Web Service call generation.



methods clearPropertyValues

Clears all property values for a given RepositoryItem. Before using

RepositoryItemSerializer.deserialize, it’s a good idea to use this method to

clear all previous values.

isPropertyDirty

Determines whether a given property value is dirty (true) or clean (false).

setPropertyDirty

Designates a given property as dirty.

getPropertyValue

Returns the value provided for a property in the Oracle ATG Web Commerce platform. If

the property does not exist in the Oracle ATG Web Commerce platform, an error of type

ATGWS.NoSuchPropertyException is thrown.

setPropertyValue

Sets a value for a property in the Oracle ATG Web Commerce platform.

getPropertyType

Returns the property’s XML data type.

setPropertyType

Specifies the XML data type for the property value.

serialize

Creates a string representation of an XML document for the RepositoryItem.

Property Class

This class represents a given property’s name and value.


properties Dirty

Determines whether a given property is dirty (true) or clean (false). If you

indicate that a property value should change by invoking the RepsoitoryItem

setPropertyValue call, this property is set to true. Once a response is returned from

the setPropertyValue call, this property is set to false.

XmlType

XML data type that will be used to represent the property’s value.

constructor Property()

Constructs an empty object representing a property.



methods getName

Returns the name of the property.

getValue

Returns the value of the property.

setValue

Sets a new value to the property.

RepositoryItemRef Class

This class represents a reference to another RepositoryItem.


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.


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 ATG Web Commerce platform for the specified

properties. If the property does not exist in the Oracle ATG Web Commerce platform, 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.


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.


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.


constructor RepositoryItemSerializationException()

Constructs an empty exception object.


2 Introduction to REST Web Services 57

2 Introduction to REST Web Services

This section provides information about and instructions for using the Oracle ATG Web Commerce

Representational State Transfer (REST) Web Services.

Oracle ATG REST Web Services provide access to ATG 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 ATG Web Commerce 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 ATG REST MVC Web Services and the Legacy REST

Web Services

• Part I, “ATG REST MVC Web Services” (page 75) 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 249) 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.

58 2 Introduction to REST Web Services

REST Web Services URLs

URLs are a central component of REST Web Services, as you access different components and functions of the

Oracle ATG Web 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 ATG 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 79) 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 251) section. For additional

information on component paths, refer to the ATG 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 63) section, or standard query and/or post


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 ATG REST Web Services communicate.

The following HTTP methods are used and supported byATG 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 ATG Web 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 ATG Web Commerce

platform server.

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

400 (Bad Request) The request could not be completed because the request URL and/or

parameters were improperly formatted.

http://www.w3.org

http://www.w3.org


Code Description

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

ATG 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 63) section for additional information.

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

Commerce is not associated with the makers of the cURL command-line tool in any way.

http://www.w3.org

http://www.w3.org

http://curl.haxx.se/


The cURL examples use several command-line flags. These flags configure the behavior of the cURL command-

line tool as it makes HTTP requests. The flags are included in examples to better show the HTTP requirements of

the Oracle ATG Web 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

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

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.

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

cURL Command Components

The following table lists commonly used cURL commands. For additional information or components, refer to

http://curl.haxx.se/.

Component Explanation

curl Names the program being invoked. The manner in which you invoke the cURL command-

line tool depends on how it has been installed in your environment.

-L Identifies an HTTP Location. If the server reports that the requested page has moved to a

different location (indicated with a Location: header and a 3XX response code), this option

will make cURL redo the request at the new location.

-v Writes verbose output while sending and receiving HTTP messages. This option exposes

more details of the HTTP transaction.

-b Uses cookies stored in the specified file to authenticate the client. In Legacy REST Web

Services, cookies are stored in a file named cookies.txt. The customer_cookies.txt

file is used for external REST MVC calls, and the agent_cookies.txt file is used for agent-

based internal REST MVC calls.

A session identifier must be stored in the file. When cURL logs into the REST Web Services,

the cookies.txt instructs it to write the cookies it receives in that file.

-c This command line option activates the cookie engine that makes cURL record and use

cookies. You can also activate cookies by using the -b cookie option. Using –c provides

the HTTP cookie file where cURL writes all cookies after a completed operation. cURL

writes all cookies previously read from a specified file, as well as all cookies received from

remote server(s). If no cookies are identified, no file will be written.

-X Use the specified HTTP method when communicating with the REST Web Services. This

example specifies that cURL should use the PUT method.

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

http://curl.haxx.se/


Component Explanation

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 ATG Web Commerce platform server uses.

Adding Control Parameters

Include control parameters with HTTP requests to alter the way that the REST Web Services handle them. For

example, if you would like the server to include an identifying string in the response, you can use the atg-

rest-user-input control parameter to specify that identifying string.

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

The following table explains the control parameters recognized by the REST Web Services server. This table also

identifies if the parameter is used in the Legacy REST Web Services or the REST MVC Web Services.

Parameter REST Version Explanation

atg-rest-append-multi-

values

Legacy Only Use this parameter to control whether setting a value

on a repository item property will add the value to an

existing set of values or replace them. This only applies to

repository item properties that hold multiple values.

atg-rest-class-

descriptor

Both Legacy

and

MVC

Use this parameter to specify the container and element

Java classes for nested object property values. For

additional information, refer to the Using Nested Multiple

Value Objects in Input (page 71) section.

atg-rest-class-type Both Legacy

and MVC

Use this parameter to specify a Java class when you

are setting an object property value. For additional

information, refer to the Using Object Values in

Input (page 69) section.

atg-rest-count Legacy Only For requests which return an array or ordered list, adding

this parameter with an integer value allows the caller to

specify the number of elements to return. Used with atg-

rest-index.

atg-rest-depth Legacy Only The number of references to traverse when rendering

output. By default it is zero which causes only the top level

object to be returned.



atg-rest-form-tag-

priorities

Legacy Only Use this parameter to specify which form handler values

should be processed first.

atg-rest-http-method Legacy Only Use this parameter to send the Legacy REST Web Server a

POST HTTP request but have it process the request as if it

used a different HTTP method.

For example you can use this control parameter to include

message body data in a POST HTTP request but have the

server process the request as if it used the GET method.

Set the value of this parameter to GET, PUT, or DELETE.

atg-rest-index Legacy Only Use this parameter to specify the entry in an array or

ordered list that will be the starting point when that array

or ordered list is returned by the server. Set the value of

the parameter to the integer value of the starting position.

Use this parameter with atg-rest-count.

atg-rest-input Both Legacy

and MVC

Use this parameter to override the default input format

configured for the server.

Set the value of this parameter to json or xml.

atg-rest-json-input Legacy Only Use this parameter to control whether the Legacy REST

Web Services server will accept standard JSON markup

for setting collection or map values on repository item

properties.

atg-rest-method Legacy Only Use this parameter to specify the Java method signature

when calling an overloaded method.

This parameter is only needed if two or more instances

of the overloaded method have the same number of

arguments.

atg-rest-null Both Legacy

and MVC

Use this parameter to set the value of a component or

repository item property to null. Set the property and

include this parameter as the new value.

atg-rest-output Both Legacy

and MVC

Use this parameter to override the default output format

configured for the server. Set the value of this parameter

to json or xml.



atg-rest-param-class-

types

Both Legacy

and MVC

Use this parameter to specify the Java classes for

multiple values in JSON functional parameters. The atg-

rest-param-class-types parameter includes three

components, container-class, element-class, and

key-class.

For example, if a functional parameter is a

java.util.ArrayList<String>, set the atg-rest-

param-class-types as shown below.

{'container-class':

'java.util.ArrayList',

'element-class':'java.lang.String'}

Use the key-class attribute when the container-

class implements java.util.Map. For example:

{'container-class':'java.util.HashMap',

'key-class':'java.lang.String',

'element-class':'java.lang.String'}

atg-rest-property-

filters

Legacy Only Use this parameter to apply property filtering to individual

Legacy REST Web Services Requests.

atg-rest-property-

filter-templates

Legacy Only Use this parameter to apply property filter templates to

individual REST Web Services Requests.

atg-rest-return-form-

handler-exceptions

Legacy Only Use this parameter to specify that the Legacy REST Web

Services server should return exceptions it encounters

when invoking form handlers in the HTTP response.

atg-rest-return-form-

handler-properties

Legacy Only Use this parameter to specify that the Legacy REST Web

Services server should return the properties of the form

handler objects it invokes in the HTTP response.

atg-rest-rql Legacy Only Include RQL query strings in this parameter.

atg-rest-simple-

response-codes

Legacy Only Include this parameter to cause the server to return OK

(200) for success rather than CREATED (201) or GONE

(410).

atg-rest-transient Legacy Only Use this parameter to create transient repository items.

Include the parameter with the value true with a Legacy

REST Web Services request to create a repository item.

atg-rest-user-input Both Legacy

and MVC

Use this parameter to specify an identifying string that

the REST Web Services server will include in the HTTP

response.


Functional Parameters for ATG REST Web Services

Functional parameters provide data that is required by the ATG 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 ATG REST Web Service or in the message body of

a POST or PUT request.

The functional parameters you provide for an ATG 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 ATGT 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.

Using URL Parameters

You can include control and functional parameters in the URL for ATG REST Web Services by using standard

URL query string syntax and URL encoding. The following ATG Legacy REST example shows a URL with two

functional parameters and a control parameter.

http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/[email protected]&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 ATG 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" : "[email protected]" , "password" : "password123" }""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/login?atg-rest-user-input=MyMessageId"

The ATG 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 252).

Setting the Content-Type Value in ATG REST Services

Set the Content-Type value when you send an HTTP message with parameters in its message body. The ATG

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 example shows an HTTP request that sets its Content-Type to application/xml.

curl -v -c cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2><atg-rest-user-input>MyMessageId</atg-rest-user-input></parameters>" http://servername:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser

* About to connect() to servername port 8080 (#0)* Trying 12.34.567.890... connected* Connected to servername (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: servername:8080> Accept: */*> Content-Type: application/xml> Content-Length: 125

XML Parameter Markup in ATG REST Services

You can use eXtensible Markup Language (XML) to format parameters in the message body of an ATG 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 ATG REST Services

You can use JavaScript Object Notation (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.

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.

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.

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 ATG REST Web Services

This section provides information about the way the ATG 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 ATG REST Web Services server will accept map and collection input when you set the values of properties

that accept multiple values.

Unless you are setting the value of a repository item, you must specify the Java classes used for the container

and the contents.


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.

You can configure the way the ATG REST Web Services server appends or replaces multiple values in a repository

item property.

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

63) section.

Legacy REST servers are configured to append values to repository item properties using the atg-rest-append-

multi-values control parameter. For information this parameter, refer to the Multiple Values in Input (page 258)

section.

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-

rest-class-type control parameter specifies the Java class of the object. Use either JSON or XML to enclose

the positional parameter.


The ATG 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=< X-Powered-By: Servlet/2.5 JSP/2.1<


* Connection #0 to host myserver left intact* Closing connection #0{"atgResponse": true}

Using Nested Multiple Value Objects in Input

To set a property value that takes a Java object that holds other Java objects, use the atg-rest-class-

descriptor control parameter to specify the Java class of the nested objects. For example, if you are setting

a property value that takes a List of Sets, indicate the Java class of the Set using the atg-rest-class-

descriptor parameter. Then include the values for the nested Sets.

The name of the parameter inside the atg-rest-class-descriptor matches the name of one of the actual

values that you supply later in the input parameter.

The input structure for nested multiple value objects builds on the structure for input objects in general.

The following example uses the atg-rest-class-descriptor control parameter to specify that the

value of the myListOfSets property is a java.util.ArrayList object. That ArrayList object holds

java.util.HashSet objects. After the atg-rest-class-descriptor, the example provides the values that

are nested inside the myListOfSets property.

{arg1 : { "atg-rest-class-type":"foo.class.WithNestedMultis", "atg-rest-class-descriptor": { "myListOfSets": { "container-class": "java.util.ArrayList", "element-class": "java.util.HashSet" } }, "myListOfSets": [["red","blue"],["green","yellow"]] }}

Here is the same object property value, encoded in XML.

<arg1> <atg-rest-class-type>foo.class.WithNestedMultis</atg-rest-class-type> <atg-rest-class-descriptor> <myListOfSets> <container-class>java.util.ArrayList</container-class> <element-class>java.util.HashSet</element-class> </myListOfSets> </atg-rest-class-descriptor> <myListOfSets> <element> <element>red</element> <element>blue</element> </element> <element> <element>green</element> <element>yellow</element> </element> </myListOfSets></arg1>


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

Using Array Types

To specify an array type in the atg-rest-class-descriptor control parameter, use the standard Java

notation for arrays.

Array Type Java Notation

String [Ljava.lang.String;

byte [B

int [I

Two-dimensional array of Strings [[Ljava.lang.String;

Using Key Class Types for Map Values

Keys for Map object values must be Strings. No other class types are supported.

Adding Date Format in Input

Use the following date format when sending dates to the Legacy REST Web Services interface.

MM/dd/yyyy HH:mm:ss z

For example, 01/29/2015 14:45:11 PDT

Setting Properties to Null

Use the atg-rest-null parameter to set the value of a component or repository item property to null. Set the

property and include this parameter as the new value.

The following example sets the value of a component property to null.


$ curl -v -b cookies.txt -X POST \-H "Content-Type: application/json" \-d "{"arg1":"atg-rest-null"}" \http://myserver:7003/rest/bean/atg/MyDog/name* About to connect() to myserver port 7003 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 7003 (#0)> POST /rest/bean/atg/MyDog/name HTTP/1.1> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5> Host: myserver:7003> Accept: */*> Cookie: JSESSIONID=S31vPTNFpLQQ7Bj6l16wh5KgDqqv18yXxwy1khgBpvqRkW5NfQRm!1359398113; DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001> Content-Type: application/json> Content-Length: 20>< HTTP/1.1 200 OK< Date: Thu, 01 Mar 2012 01:18:50 GMT< Transfer-Encoding: chunked< Content-Type: application/json; charset=UTF-8< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=< X-Powered-By: Servlet/2.5 JSP/2.1<* Connection #0 to host myserver left intact* Closing connection #0{"atgResponse": true}


Part I. ATG REST MVC Web ServicesThe REST MVC Web Services API was designed to address limitations with the Legacy REST API. The REST MVC framework

uses 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 77) 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 79) 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 121) provides detailed information on existing customer-facing REST

service calls, with examples and component configuration information

• Internal REST MVC Service Call Examples (page 175) provides detailed information on existing internal, or agent-facing

REST service calls. This section is intended for users of Oracle ATG Web Commerce Service Center to REST services for call

center agents

3 Installing and Configuring the REST MVC Server 77

3 Installing and Configuring the REST

MVC Server

The following section describes the installation and configuration of the REST server.

Installing the REST MVC Module

The REST MVC framework is contained within the REST module. Install the REST MVC module using the ATG

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 ATG modules, refer to the

ATG 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 <ATG10dir>/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. Actor-chains that are accessed only through

nested actors need not be registered. For detailed information on actor-chains, refer to The REST MVC Definition

Framework (page 79) section.

Note: When you add the actor-chain, you can 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

registeredUrls+=\

/atg/userprofiling/ProfileActor/login,\

/atg/userprofiling/ProfileActor/login-success,\

78 3 Installing and Configuring the REST MVC Server

/atg/userprofiling/ProfileActor/login-error,\

Note that if you enter only the actor, the default actor-chain will be used.

3. Save the file.

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

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 ATG 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 actors and component

actors that will 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 92) and The Component Element (page 84) sections. For information on getting the

Dynamo session confirmation number, refer to the Getting the Session Confirmation Number (page 122)

section.

4 The REST MVC Definition Framework 79

4 The REST MVC Definition

Framework

ATG REST MVC Web Services allow you to use HTTP requests to work with any ATG 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 an ATG REST MVC service, you send a URL. The URL must be explicitly defined and registered

with the REST Web Services. If registered, as outlined in the Enabling REST Services (page 77) section, the URL

references controllers, which are known as actors. Each actor, which is configured using XML definition files,

interfaces with a resource, such as a JSP page, a form handler, a servlet bean, a Nucleus component or another

chain of actors, or actor-chains.

These actors generate a ModelMap, which can be filtered and transformed as necessary. The ModelMap is a map

of maps that is populated by actors. The response that is rendered is based on the content 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 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:

80 4 The REST MVC Definition Framework

1. The REST Service uses a URL that begins with /rest/model and has been registered with the

ActorChainRestResgistry service. In this example, the URL is:

/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder

This URL contains not only the CartModifierActor Nucleus component, but the addItemToOrder actor-

chain.

The REST Service also verifies the user’s access using the AccessControllerService.

2. The REST Service initializes the actor context from the REST control parameters and the URL. The actor-

context is then passed to the ActorChainService. Because the addItemToOrder actor-chain calls the /

atg/commerce/order/purchase/

CartModifierFormHandler, a formActor is invoked. The /atg/commerce/order/ShoppingCart

component requires that a componentActor is also invoked. Refer to the XML Definition Elements (page

81) 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 the Bean Filtering (page

108) 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 then sent back to the client.

The following diagram shows the flow of the REST service call:

Actor Types

The REST MVC API’s modular and extensible functionality is based on actors, which uses a number of different

types of actors to perform a variety of functions. The atg.service.actor.Actor interface contains the

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

ATG REST MVC requests use a /rest/model URL to process requests against the actor framework. The general

format for a REST MVC URLS is:

http://host:port/rest/model/actor_component/tail

The format variables are:

• host – The REST server

• port – (Optional) The port from which users access the REST services

• actor_component – The Nucleus path for a Nucleus component that implements the actor interface

• tail – (Optional) Any attribute that can be processed by a URIProcessor. For chained actors, the tail is the

chain-id

A typical request may be similar to the following call that adds an item to a shopping cart:

http://rest.company.com:8280/rest/model/atg/commerce/order/purchase/ CartModifierActor/addItemtoOrder

Refer to the External REST MVC Service Call Examples (page 121) and Internal REST MVC Service Call

Examples (page 175) sections to see examples of request URLs.

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.

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:

<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 actor one or more actors that include or output elements.

An actor-chain contains the following:

Attribute/Elements Description

id Defines the chain-id. This attribute is used during the XML combination process,

as well as to identify the chain to execute.

transaction Provides transaction demarcation for the chain. For information on the supported

transaction demarcation types, refer to the ATG Repository Guide. The default value is

TX_SUPPORTS.

Note: If you are creating REST MVC Web Service calls it is important to note that

Profile and Order-related form handlers require that the transaction not be defined

prior to executing.

actors An actor-chain can have one or more actors that include 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 pass from the parent to the child actor-chain.

Actor elements contain the following:

Attribute/Element Description

return-model-var Provides the variable name of the child chain returned by the ModelMap. The

ModelMap that is returned from the child chain could 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.



id The actor ID. This attribute is used for actor ordering.

name The Nucleus path of the actor component to invoke.

depends This element defines actors that must be executed prior to the execution of the

current actor. There can be multiple depends elements associated with an actor.

depends-if-

present

This element defines actors that, if present, must be executed prior to the execution

of the current actor. There can be multiple depends-if-present elements

associated with an actor.

input This element defines each actor’s input. Actors can have multiple input elements.

output This element defines each actor’s output. output elements create a map entry in a

ModelMap. Actors can have multiple output elements.

The ActorContext and ModelMap of the parent actor are not passed to the child actor. The following example

shows how information can be passed from a child actor-chain to a parent actor-chain. Note that request

parameters do not need to be passed in explicitly as inputs; you can pass in their variables:

<! – Call another actor-chain to get quantity -><actor id="addItem" name="/atg/commerce/gifts/NewListActor" return-model-var="addItemVar"> <input name="quantity" value="${quantity}"/> <output name="quantity" value="${addItemVar}"/ ></actor>

In the above example, the parent actor-chain contains a quantity ModelMap. 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 106) 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's 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>

The Component Element

The component element executes a method within a component or sets property and outputs values from a

component to the output ModelMap. It can also resolve a component or invoke a method on a component.

The component element contains the following:



name Identifies the Nucleus path of the component.

method (Optional) Identifies the name of the method to be executed. Use only when

invoking a method.

component-var Provides a variable name that accesses the component’s properties.

method-return-var Identifies the variable name that accesses the method invocation’s returned

value.

id This attribute defines the actor ID, and is used for actor ordering.

set-property-

requires-session-

confirmation

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

property is set to true by default.

invoke-method-

requires-session-

confirmation

By default, all method calls require session confirmation numbers. This property

is set to true by default.



depends-if-present This element defines actors that, if present, must be executed prior to the

execution of the current actor. There can be multiple depends-if-present

elements associated with an actor

input This element defines each actor’s input. Actors can have multiple input

elements.

output This element defines each actor’s output. Output elements create a map entry

in a ModelMap. Actors can have multiple output elements.

Example: Resolving a Component

The following example resolves a component that sends output from the properties of the component to

a ModelMap. In this example, the component class instance is saved in the shoppingCart variable of the

ActorContext.

<component id="shoppingCart" name="/atg/commerce/ShoppingCart" component-var="shoppingCart" > <output name=orderId" name="orderId" value="${shoppingCart.last.id}"/ ></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" 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"

boolean [Z for example, class-name="[Z"

byte [B for example, class-name="[B"

float [F for example, class-name="[F"

int [I for example, class-name="[I"


Example: Passing Multiple Arguments

To pass more than one argument into a method, you must specify the index attribute on the inputs so that

the input arguments for the method are ordered. For complex object types, you may need to convert the string

value to an object by specifying a PropertyEditor or TagConverter. Any registered property manager can

be used to convert inputs into complex object types so that they may pass method parameters. The system

attempts to coerce the input value to the correct type of object based on the method’s expected input type.

If the method is overloaded, you may need to specify the PropertyEditor to disambiguate between the

overloaded methods. Also, it is usually necessary to define a PropertyEditor for collections of complex

objects since the type of objects contained in the collection cannot be determined at run time.

<component id="methodEx" name="/my/component/Example" method="doSomething" component-var="example" method-return-var="rtn"> <!-Fictitious DateListPropertyEditor that converts pDateRange into a list of dates --> <input name="pDateRange" value="${param.dateRange}" index="0" property-editor="atg.nucleus.PropertyEditors.DateListPropertyEditor"/> <!-We did 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="paymentFroupFormHandler" 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.

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 ATG 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 ATG servlet beans. The DropletActor executes ATG servlet beans

and adds object values to the ModelMap based on the meta-data.

The droplet element contains the following:


name This is the Nucleus path of the ATG servlet bean.

var Exposes the current frame of the Dynamo param stack as an attribute.


oparam Droplets may have one-to-many oparams.



depends-if-

present



associated with an actor


output This element defines each actor’s output. output elements create a map entry in a


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:


name 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"> <!-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 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 the client, using the request parameter, or 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"/> <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 103) 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:

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


name This is the Nucleus path of the form handler.

handle The name of the handle method to execute.

var The variable name that can access form handler properties and exceptions.


requires-session-

confirmation

By default, all form handler submissions require session confirmation numbers.

This property is set to true by default.

depends This element defines actors that must be executed prior to the execution of

the current actor. There can be multiple depends elements associated with an

actor.




execution of the current actor. There can be multiple depends-if-

present elements associated with an actor.

input This element defines each actor’s input. Actors can have multiple input

elements.

output This element defines each actor’s output. Output elements create a map entry

in a ModelMap. Actors can have multiple output elements.

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:

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


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

<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 ATG Platform Programming Guide.

The following example shows how to disable session confirmation numbers for a FormActor:

<actor-chain id="login" transaction="TX_SUPPORTS"> <form id="profileFormHandler-login" name="/atg/userprofiling/ProfileFormHandler" handle="login" var="profileFormHandler" requires-session-confirmation="false"> <input name="value.login" value="${param.login}" /> <input name="value.password" value="${param.password}" /> <input name="loginErrorURL" value="/rest/model/atg/userprofiling/ProfileActor/login-error"/> <input name="loginSuccessURL" value="/rest/model/atg/userprofiling/ProfileActor/login-success"/> </form></actor-chain>

Note that the /atg/dynamo/service/actor/Configuration.enforceSessionConfirmation flag can

also be used to disable this requirement during development. Again, it is recommended that this flag is disabled

only in your development environment.


Example: Form Error Handling

When a form handler encounters an error, it typically processes the error by adding a DropletException to

the form handler and forwarding to an error URL. The handle method returns false, indicating that a forward

or redirect has occurred, and the actor-chain immediately terminates. Success or error URLS can be supplied to

the form handler using the input element. If the error URL has been defined to use another actor-chain, a new

ModelMap and ActorContext is created to issue the response.

For example, to invoke the cartModifierActor to pass an error URL that will re-render the Add Item to Order

page if there is an error:

# /atg/commerce/order/purchase/cartModifierActor<actor-template default-chain-id="addItemToOrder"> <actor-chain id="addItemToOrder" transaction="TX_SUPPORTS"> <form id="cartModifierFormHandler" name="/atg/commerce/order/ purchase/CartModifierFormHandler" var="cartModifierFormHandler" handle="addItemToOrder"> <input name="catalogRefIds" value="${param.catalogRefIds}"> <tag-converter class-name="atg.droplet.ArrayTagConverter"/> </input> <input name="productId" value="${param.productId}"/> <input name="quantity" value="${param.quantity}"/> <input name="locationId" value="${param.locationId}"/> <input name="siteId" value="${param.siteId}"/>

<input name="addItemToOrderErrorURL" value="/model/atg/commerce/order/ purchase/CartModifierActor/addItemToOrder-error"/> <input name="addItemToOrderSuccessURL" value="/model/atg/commerce/order/ purchase/CartModifierActor/addItemToOrder-success"/> </form> </actor-chain> <actor-chain id="addItemToOrder-error" transaction="TX_SUPPORTS"> <actor id="error" name="/atg/commerce/order/purchase/CartModifierActor" chain-id="error" return-model-var="model"> <output id="model" add-map-children="true" value="${model}"/> </actor> </actor-chain> <actor-chain id="addItemToOrder-success"> <actor id="order" name="/atg/commerce/ShoppingCartActor" chain-id="summary" return-model-var="model"> <output id="model" add-map-children="true" value=${model}" /> </actor> </actor-chain>

<actor-chain id="error" transaction="TX_SUPPORTS"> <component id="fh" name="/atg/commerce/order/purchase/CartModifierFormHandler" component-var="fh"> <output id="formError" name="formError" value="${fh.formError}"/> <output id="formExceptions" name="formExceptions" value="${fh.formExceptions}" filter-id="detailed"/>  <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 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 ATG platform-based form handlers, the form handler response is similar to the following:

{"formError":true, "formExceptions":[{"localizedMessage":"The password andlogin do not match","errorCode":"invalidPassword"}]}

The JSP Element

The jsp element executes a JSP page and sends output object values to the output ModelMap. JSPActors

typically write to variables that are mapped by the JSPActor definition.

Note that existing JSP templates that were created with older versions of the ATG 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:

Attribute Description


page This is the absolute path of the JSP URL, excluding the context root.

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

present



associated with an actor.


output This element defines each actor’s output. Output elements create a map entry in a


The following is an example of a jsp element:

<actor-chain id="shippingMethods"> <jsp url="/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" />

<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 previous versions of ATG REST JSP templates to the JSPActors:

<jsp id="displayCart" page="/orderDetail.jsp" context="mobile" response-var="orderJSON" > <output id="orderOut" name="order" value="${orderJSON}" embed-for-mime-type="application/json"/></jsp>

The Output Element

The output element defines a map entry in a ModelMap. Once the actors are executed, the output values are

evaluated and added to the ModelMap based on the name attribute.


The output element contains the following:



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





elements associated with an actor.

message The output tag supports internationalized messages that are added to the

ModelMap.

The following is an example of an output element:

<output name="globalInfo" value="${CSREnvironmentTools}" filter-id="globalTemplate"/>

The filter-id identifies the filter for the BeanFilterService to apply. Refer to the Bean Filtering (page

108) section for further information.

The output tag supports localized message tags, which add internationalized messages to the ModelMap. By

default, all messages are localized based upon the current user’s locale, however, the locale can be passed in

using the message tag.


The message element contains the following:


id This attribute defines the message ID.

locale-code The locale that will be used to localize the message, for example, en_US. If not

available, the system will use the ServletUtil.userLocale setting.

bundle Identifies the resource bundle that contains the resource key.

key The resource key identified by the resource bundle.

message-param If message parameters are required during the resource lookup, you can use the

attributes used by this element:

id – The ID of the message param.

value – The value to pass.

The following is an example of an output element with a message element. Messages are, by default, localized

using the user’s locale, however, you can set the locale using the message tag:

<output id="error" name="error" <message id="PRODUCT_NOT_IN_CURRENT_CATALOG" bundle="atg.commerce.catalog.custom.UserResources key="PRODUCT_NOT_IN_CURRENT_CATALOG"> <message-param id="arg0" value="${(productId != null) ? productId : param.productId"/ > </message></output>

The output from the example above would be:

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

The Input Element

The input element defines actor inputs and is used to pass values to the actors. The input element is used for

all actor types.

The input element contains the following:


name 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 84)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 92)section for additional

information.

index Used only by the ComponentActor in a method call, this attribute defines the

order of the method’s parameters. Refer to The Component Element (page

84)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 actor’s execution. However, in the depends-if-present element, the specified actor is not

required in the actor-chain. This element is best used when an actor in the actor-chain may not be available. The

element allows you to identify actor order, but will not generate an error if the requirements are not met.

Both the depends and the depends-if-present elements contain the id attribute, which identifies the ID of

the actor that must run before the current actor.

Ordering Actors

The depends and the depends-if-present elements control actor-chain ordering. If your actors are defined

in a single file, the order in which you define your actors is the way they will be executed. However, if you

have actors that you have defined in various overriding layers and you want to change their order, you must

identify the order using the depends and depends-if-present elements. If actor order is not important, these

elements are not required in the actor definition. For example, if you have a base configuration file for shipping

groups:

<actor-template>


<droplet id="ApplicableShippingGroups" name="/atg/commerce/custsvc/ order/ApplicableShippingGroups" var="applicableShippingGroups">  <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 be:

<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>ShippingGroupDroplet"</depends> </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.

This element contains the following:


id The actor ID. This attribute is used for actor ordering.

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





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

$class=atg.service.actor.ActorChainService

definitionFiles+=/custom/atg/commerce/orderConfirmationActor.xml

2. Create a orderConfirmationActor XML file that contains the following, where the actor-chain defines a

ComponentActor:

/custom/atg/commerce/order/purchase/orderConfirmation.xml

<actor-template>


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

<!-atg.service.actor.ComponentActor processes this tag. -->

<!-this tag adds the component to the model map -->

<component id="shoppingCart" name="/atg/commerce/ShoppingCart"

component-var="shoppingCart">

<output name="orderId" value="${shoppingCart.last.id}"/>

</component>

</actor-chain>

</actor-template>

Example: Creating a Shipping Address Actor

The following is an example that creates a Nucleus component and an XML file that defines an actor-

template instance that allows you to access shipping address data.

1. Define the Nucleus component and identify the XML file that defines the actor-template:

/custom/atg/commerce/ShippingAddressesActor.properties


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

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


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:

Object Description

request This object maps to the current request.

session This object maps to the user’s session.


Object Description

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.

objectParam.name Maps a request parameter name to an object value.

header.name Maps a header name to a single string value.

headerValues.name Maps a header name to an array of string values.

cookie.name Maps a cookie name to a cookie object.

atgActorModel Maps the current actor-chain’s modelMap. This does not reference the parent

chain’s modelMap.

nucleus Maps a Nucleus component.

Accessing Actor Context Variables

Actor context variables and attributes are available only for the duration of the actor-chain. Each nested actor-

chain or child actor-chain is given a new ActorContext and ModelMap, and is unable to reference their parent’s

ActorContext and ModelMap. However, all actor variables are added to the ActorContext as attributes, which

you can access.

To access ActorContext, request or session attributes, you can map the attribute to a value using the

${order.id} syntax or ${commerceItems[0]} array notation.

For example, you could resolve a Nucleus component using the following EL expression:

${nucleus['/atg/commerce/ShoppingCart'].current}

If a variable name does not start one of the implicit objects listed in the Working with Implicit Objects (page

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

Combining Actor Definitions

You can use xml-combine to customize the elements used in REST. The following attributes are used during the

xml-combine. For additional information on XML combining, refer to the ATG Page Developer's Guide.

Element Match Attribute

actor-chain id


Element Match Attribute

form id

jsp id

component id

actor id

input name

message id

message-param id

output id

oparam name

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"> <property name="email" /> <property name="lastName" /> <property name="firstName" /> <property name="dataSource" /> <property name="homeAddress.postalCode" target="homeAddress.postalCode" /> <property name="gender" /> <property name="dateOfBirth" /> </filter> </bean></bean-filtering>

Bean filters combine filter definitions from all classes or interfaces for an object using the filter-id property.

You can also include other bean filters within a bean filter by using the include-filter attribute.

It is best to define a filter for every object, so that you can control its output. Note that if an object has no filters

defined, it will output all properties.

The following XML values are defined by the atg/dtds/beanfilter/beanFiltering_1.0.dtd file:

The Bean Element

The bean element defines a filter for a Java bean class or interface that is in the ModelMap. The filter can be

defined at any level of the class and interface hierarchy, and will automatically apply classes and interfaces that

have a filter with the same ID. Note that it is best to insert whole objects into the ModelMap and allow bean

filtering to control the way that the object is viewed. By defining a filter for every object you can control the

output for that object.

The bean element contains the following attributes:


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></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 common in one filter and 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>  <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

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:


name The name that the property will use when sending the response.

target The name of the property that is being read from the Java servlet bean or

repository. If no target is supplied, the value of the name attribute will be used

instead.

property-

customizer

The Nucleus path of a component that implements the

atg.service.filter.bean.PropertyCustomizer interface. Use these

attributes to transform properties if needed.

hidden If this property is set to true, the property will be excluded from the response.

This property is set to false by default.

filter-id Applies a filter by ID that matches the class of the repository item type of the

property value. Note that the filter-id of a bean filter property will override

the filter-id attribute of an actor output element. Objects that are properties

of this element use this filter-id. For example, if a filter-id is applied to

the user repository-item, the same filter-id will be applied to the contact

repository-item when filtering the homeAddress property of the user.

Working with Property Customizers

You can transform properties using the property-customizer attribute. For example you could mask a credit

card number by creating a maskedCreditCardNumber property:

<property name="maskedCreditCardNumber" property-customizer="/atg/rest /filtering/customizers/CreditCardNumberPropertyCustomizer"/>

You can also retrieve other properties using this syntax.

If the target attribute does not start with a $, it will be evaluated as a DynamicBean.getPropertyValue() if

the object is a DynamicBean. Both item-descriptor and bean elements can use this syntax. Note that the

properties that are returned by default can be added to using xml-combine.

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>

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:


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 112) 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 four of the 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:



name The path name to the repository.

item-descriptor The name of the item-descriptor to filter upon. The item-descriptor

elements are nested under the repository element so that item-descriptors

from the same repository are grouped together in the XML file. If you xml-

combine any item-descriptor definitions, they are presented together under the

repository element in the combined XML.

The following is an example of the repository element:

<repository name="/atg/commerce/catalog/ProductCatalog"> <item-descriptor name="media-external" default-filter="summary"> <filter id="default"> <property name="url"/> <property name="mimeType"/> </filter> </item-descriptor></repository>

The alias element defines an alternate component path for the repository definition. The name attribute of the

alias element defines the path of the repository.

The Item-Descriptor Element

The item-descriptor element filters the properties returned for an item-descriptor placed in the

modelMap. It uses the following attributes:


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 if 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 ATG Dynamo Server Admin to view the filters used in your environment. Select the /atg/dynamo/

service/filter/bean/XmlFilterService to see the filter configuration. Click on a repository or a servlet

bean to view filter information:

Note that you cannot use the Dynamo Server Admin to modify these filters. To make modifications to these

filters, modify the beanFilteringConfiguration.xml file. Once you have made the changes, use the

Dynamo Server Admin to access /atg/dynamo/service/filter/bean/BeanFilterService and run the

reinitialize method to implement your changes.

REST MVC Access Control

Whenever a REST 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 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= /atg/rest/userprofiling/AllAccessController,\ /rest/model/atg/userprofiling/InternalProfileActor/logout= /atg/rest/userprofiling/LoggedInAccessController,\ /rest/model/atg/userprofiling/InternalProfileActor/logout-error= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/userprofiling/SecurityConfirmationActor= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/rest/SessionConfirmationActor/getSessionConfirmationNumber= /atg/rest/userprofiling/AllAccessController, \ /rest/model=/atg/rest/userprofiling/NonTransientAccessController

accessControllers=+\ /rest/model/atg/userprofiling/ProfileActor/logout= /atg/rest/userprofiling/LoggedInAccessController,\ /rest/model/atg/userprofiling/ProfileActor/logout-success= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/userprofiling/ProfileActor/logout-error= /atg/rest/userprofiling/AllAccessController, \ /rest/model/atg/rest/SessionConfirmationActor/getSessionConfirmationNumber =/atg/rest/userprofiling/AllAccessController

The following example of the /atg/rest/userprofiling/LoggedInAccessController shows how to set

the access controller using the enabled parameter, as well as which rule to use to determine access. If access is

denied, the SecurityStatusActor will identify the error and redirect the user to an error URL:

$class=atg.userprofiling.RuleAccessControllerenabled=true# Rules used to determine whether access should be allowedruleSetService=/atg/rest/targeting/LoggedInRuleSetService# URL to redirect to if access is denieddeniedAccessURL=/rest/model/atg/userprofiling/SecurityStatusActor/


authenticationRequired

Creating a New REST Call

The following section identifies the steps needed to define a new REST call.

1. Define an actor-chain component.

When you define an actor-chain component, define it in the same module as the component it references.

For example:

/atg/commerce/custsvc/order/CommitOrderActor.properties


definitionFile=/atg/commerce/custsvc/order/commitOrderActor.xml

2. Define the actor-chain definition XML file.

It is best to define success and error URLs in the actor rather than on the client-side. You should also define a

success and error URL per form handler. You can use nested actors to reference a shared error handler.

<?xml version="1.0" encoding="UTF-8"?>

<actor-template default-chain-id="commitOrder"

xsi:noNamespaceSchemaLocation="http://www.atg.com/xsds/ActorChain.xsd"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

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

<form id="commitOrderFormHandler"

name="/atg/commerce/custsvc/order/CommitOrderFormHandler"

handle="commitOrder" var="commitOrderFormHandler">

<input name="allowEmptyOrders" value="${param.allowEmptyOrders}"/>

<input name="salesChannel" value="${param.salesChannel}"/>

<input name="siteId" value="${param.siteId}"/>

<input name="commitOrderErrorURL"

value="/model/atg/commerce/custsvc/order/

CommitOrderActor/commitOrder-error"/>

<input name="commitOrderSuccessURL"

value="/model/atg/commerce/custsvc/order/

CommitOrderActor/commitOrder-success"/>

</form>

</actor-chain>

<actor-chain id="commitOrder-success" transaction="TX_SUPPORTS">

<actor id="success" name="/atg/commerce/custsvc/order/

OrderConfirmationActor" chain-id="orderConfirmation"

return-model-var="model">

<output id="model" add-map-children="true" value="${model}"/>

<actor>

</actor-chain>

<actor-chain id="commitOrder-error" transaction="TX_SUPPORTS">

<component id="fh" name="/atg/commerce/custsvc/order/

CommitOrderFormHandler" filter-id="full"

<output id="concurrentUpdate" name="concurrentUpdate"


value="${fh.concurrentUpdate}"/>

<output id="order" name="order" value="${fh.concurrentUpdate ?

fh.order : null}" filter-id="full"

</actor-chain>

</actor-template>

When creating a form handler, it is best to define success and error chains the base module, for example DCS,

and xml-combine success chain in the application module.

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

78) section for further information.

3. If required, create a success chain using xml-combining in the application module.

For example, the following example, when xml-combined, will display an order confirmation after the order

has been committed. Note that for form handlers, you should define success and error chains in the base

module and create the xml-combined success chain in the application module:

<actor-template default-chain-id="commitOrder">

<actor-chain id="comittOrder-error" transaction="TX_SUPPORTS">

</actor-chain>

<actor-chain id="commitOrder-success">

<actor id="success" name="/atg/commerce/custsvc/order/

OrderConfirmationActor" chain-id="orderConfirmation"

return-model-var="model"/>

<output id="model" add-map-children="true" value="${model}"/>

</actor>

</actor-chain>

</actor-template>

4. Register the actor-chains in the ActorChainRestRegistry so that they are enabled for REST access.

By default, no actors are registered. Actor-chains accessed from REST or from success and error ULRs 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.

# /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 wrapper classes 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/

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. 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 78) section. To disable the session

confirmation numbers, set the enforceSessionConfirmation parameter in your local /atg/dynamo/

service

/actor/Configuration.properties file to false. Note that the following type of ambiguous error will

occur when session confirmation is disabled:

HTTP Status 409 - Your session expired due to inactivity.type - Status reportmessage - Your session expired due to inactivity.description - The request could not be completed due to a conflict with thecurrent state of the resource.

5 External REST MVC Service Call Examples 121

5 External REST MVC Service Call

Examples

The following REST MVC services have been made available so that you can begin issuing them immediately

upon installation of your REST configuration.

As described in previous sections, REST MVC calls are based on actors that perform specific functions. This

section is organized by tasks that each actor performs for external-facing customers. For ATG REST MVC calls for

agents, refer to the Internal REST MVC Service Call Examples (page 175)section.

Note that this section contains information on desktop REST MVC calls. For information on REST calls used by

mobile applications, refer to the CRS-IUA Overview document.

External Service Call Workflow Example

The following diagram shows an example of a typical customer’s workflow that contains various REST service

calls:

Each of these service calls performs an action within the Add Item to Cart workflow, starting with a customer

logging in to the REST Server and ending when the customer logs out of the REST server.

122 5 External REST MVC Service Call Examples

Note: The following examples are provided as guidelines for working with External REST MVC calls. The

responses returned by your server may vary based upon your environment’s configuration.

Getting the Session Confirmation Number

The first actor that must be invoked is the Dynamo Session Confirmation actor. As described in the Using

Dynamo Session Confirmation Numbers (page 78) section, the session confirmation number is used by

the REST Web Services to provide secure access to the REST calls. The Form Element (page 92) and The

Component Element (page 84) 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}

Working with Customers

The /atg/userprofiling/ProfileActor contains actor-chains that perform the following:

Actor-Chain Description

login Allows a customer to log into the site.

logout Allows a customer to log out of a site.

create Creates a customer profile.

update Updates a customer profile.

detailed Views a customer profile using the detailed filter.

summary Views a customer profile using the summary filter.

creditCards Provides the credit cards associated with the customer profile.



currentCatalog Provides the customer’s current catalog.

addresses Provides the addresses associated with this customer profile.

Logging In Customers

The login actor-chain is used to log the customer into the site and verify the appropriate login and password

credentials.

Parameter Description

login The customer login, for example, [email protected].

password The customer’s password.

Customer Log In Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json"-d "{ "login" : "[email protected]" , "password" : "password123" }""http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/login"

If the log in information proved to be incorrect, the following exception might occur:

{"formError":true,"formExceptions":[{"localizedMessage":"The password andlogin do not match","errorCode":"invalidPassword"}]}

Logging Out Customers

The logout actor-chain is used to log the customer off of the site.

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"

If the log out fails, the following exception might occur:

{"formError":true,"formExceptions":[{"localizedMessage":"The password and


login do not match","errorCode":"invalidPassword"}]}

Creating New Customer Profiles

The create actor-chain is used to create a new customer profile.


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 Realms, this indicates the ID of the

realm. Refer to the ATG Commerce Programming Guide for information on

realms.

firstName The first name of the customer.

middleName The middle name or initial of the customer.

lastName The last name of the customer.

email The customer’s e-mail address.


confirmPassword Re-enter the customer’s password to verify.

login The customer’s log in name.

dateOfBirth The customer’s date of birth.

gender The customer’s gender.

homeAddress.address1 The first address line of the customer’s home address.

homeAddress.address2 The second address line of the customer’s home address.

homeAddress.address3 The third address line of the customer’s home address.

homeAddress.city The city associated with the customer’s home address.

homeAddress.state The state associated with the customer’s home address.

homeAddress.postalCode The postal code associated with the customer’s home address.

homeAddress.country The country associated with the customer’s home address.

homeAddress.phoneNumber The phone number of the customer’s home address.

homeAddress.companyName A company that is associated with the home address.

homeAddress.county A county that it associated with the home address.



homeAddress.jobTitle A job title associated with the customer’s home address.

homeAddress.faxNumber A fax number associated with the customer’s home address.

homeAddress.prefix A prefix used when creating the home address, for example, Mr. or Dr.

homeAddress.suffix A suffix used when creating the 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":\"Jackson\","email":\"[email protected]\", "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.


autoLogin Determines if a cookie should be used during logging in. Setting this to

true allows a customer to log in automatically.

realmId If your environment is set up to use realms, this indicates the ID of the

realm. Refer to the ATG Commerce Programming Guide for information on

realms.






email The customer’s e-mail address.


confirmPassword Re-enter the customer’s password to verify.

login The customer’s log in name.


gender The customer’s gender.

homeAddress.address1 The first address line of the customer’s home address.

homeAddress.address2 The second address line of the customer’s home address.

homeAddress.address3 The third address line of the customer’s home address.

homeAddress.city The city associated with the customer’s home address.

homeAddress.state The state associated with the customer’s home address.

homeAddress.postalCode The postal code associated with the customer’s home address.

homeAddress.country The country associated with the customer’s home address.

homeAddress.phoneNumber The phone number of the customer’s home address.

homeAddress.companyName A company that is associated with the home address.

homeAddress.county A county that it associated with the home address.

homeAddress.jobTitle A job title associated with the customer’s home address.

homeAddress.faxNumber A fax number associated with the customer’s home address.

homeAddress.prefix A prefix used when creating the home address, for example, Mr. or Dr.

homeAddress.suffix A suffix used when creating the 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.

Edit Customer Profile Example

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


"{"firstName":\"Joe\", "middleName":\"B\", "lastName":\"Jackson\","email":\"[email protected]\", "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"?atg-rest-output=xml"

Viewing the Shopping Cart

The /atg/commerce/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.

Parameters: None

View Shopping Cart Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/ShoppingCartActor/detailed"


{"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": "[email protected]", "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": [{ "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", "faxNumber": null, "phoneNumber": "6176378687", "county": null, "email": "[email protected]", "prefix": null, "firstName": "John", "jobTitle": null }, "creditCardType": "Visa", "orderId": null }], "profileId": "230000", "creationTime": 1363291121877, "relationships": [{ "id": "r110006", "amount": 0, "relationshipType": "SHIPPINGQUANTITY", "returnedQuantity": 0, "shippingGroupId": "sg140009", "commerceItemId": "ci11000002", "quantity": 1 }], "totalCommerceItemCount": 1}}


Working with the Shopping Cart

The cartModifierActor contains several actor-chains that modify the customer’s shopping cart. The path for

this actor is /atg/commerce/order/purchase/CartModifierActor.

This actor contains the following actor-chains:


addMultipleItemsToOrder Adds multiple items to a shopping cart.

addItemToOrder Adds items from a catalog, wish/gift list to a shopping

cart.

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

setOrder Updates the shopping cart by SKU ID.

setOrderByCommerceId Updates the shopping cart by Commerce ID.

setOrderByRelationshipID Updates the shopping cart by 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 ID.

RemoveItemFromOrderByRelationshipId Removes an item from the shopping cart using the

Relationship ID.

moveToPurchaseInfoByCommerceId Saves the shopping cart and continues to the next step in

the checkout process.

Adding Multiple Items to the Shopping Cart

The addMultipleItemsToOrder actor-chain is used when adding more than one item to shopping cart.


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.

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.

locationId Used only for in-store pickup. This identifies the location of the store.

siteId Identifies the site associated with the product.

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.

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

Adding Items to a Shopping Cart

The addItemToOrder actor-chain is used to add a single to a shopping cart. It also is used to add an item from a

customer’s gift/wish list to a shopping cart, as well as adding an item to an in-store pickup order:


catalogRefIds The catalog reference ID.





locationId Used only for in-store pickup, identifies the location of the store.

addToWishlist Boolean parameter used only for adding wish list items to the shopping cart.

giftlistId Identifies the gift list ID.



giftlistItemId Used only for adding gift/wish list items. Identifies the list item ID.

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

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

This actor-chain is used to remove items from the order and then adds it to the order.



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.

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"

Continuing the Checkout Process

The moveToPurchaseInfoByCommerceId actor-chain starts the checkout process. The current order’s

commerce items and quantities must be passed in to initiate the checkout process.


commerceItem The order’s commerce item.

quantity The quantity of the item.

Continue the Checkout Process Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" –d"{\"ci4000006\" : \"2\"}" "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.



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.


createOneInfoPerUnit A Boolean parameter that controls whether 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"



{ "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": "[email protected]", "state": "MA", "address1": "1 Main St", "address2": null "firstName": "John", "city": "Cambridge", "country": "USA" }, "stateDetail": null }}, "shippingInfos": {"ci11000002": [{ "handlingInstructionInfos": [], "commerceItemId": "ci11000002" }]}}

Specifying the Default Shipping Group

The SpecifyDefaultShippingGroup actor-chain identifies the default shipping group for the current order.


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.

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"

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.


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.


cisiList.quantity The original quantity value that needs to be split.

cisiList.splitQuantity The quantity that should be moved to the other shipping

group.

cisiList.shipppingGroupName This is the name of the shipping group in which the item

will be available.

cisiList.splitShippingGroupName This is the name of the split shipping group.

Split Commerce Items into Different Shipping Groups Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"cisicount\" : \"1\", \"cisiList\" :{ \"atg-rest-class-type\":\"java.util.ArrayList\", \"atg-rest-values\": [{ "atg-rest-class-type":"atg.commerce.order.purchase.CommerceItemShippingInfo", \"quantity\" : \"5\",\"splitQuantity\" : \"2\", \"shippingGroupName\" : \"Address\",\"splitShippingGroupName\" : \"Address##0\"}]}}""http://localhost:8280/rest/model/atg/commerce/order/purchase/ShippingGroupActor/splitShippingInfos"

Displaying Available Shipping Methods

The AvailableShippingMethodsActor is used to display the available shipping methods. The path to this

actor is: /atg/commerce/pricing/AvailableShippingMethodsActor.

This actor contains the getAvailableShippingMethods actor-chain:

Parameters: None

Display Available Shipping Methods Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/pricing/AvailableShippingMethodsActor/getAvailableShippingMethods"


Creating a New 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.


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.

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:



nickname The nickname associated with the shipping group to update.


middleName The middle name or initial 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.





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

Edit Shipping Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"nickname\": \"Address\",\"firstName\": \"John\",\"lastName\":\"Doe\",\"address1\": \" 2 Main St.\",\"city\": \"Wilmington\",\"state\":\"MA\",\"country\": \"USA\",\"postalCode\": \"01872\" }""http://localhost:8280/rest/model/atg/commerce/order/purchase/UpdateHardgoodShippingGroupActor/updateHardgoodShippingGroup"

Working with the Billing Page

The PaymentGroupActor contains several actor-chains that allow the customer to work with the billing

page, and to specify payment groups. The path for this actor is /atg/commerce/order/purchase/

PaymentGroupActor.



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.


init This Boolean parameter, if true, will clear payment group information and

the Commerce Identifier Payment Info (CIPI) , and initialize payment groups

and the Commerce Item Shipping Info (CISI).

createAllPaymentInfos This parameter will look for all Commerce Identifier Payment Info (CIPI), and

returns information from all payment groups.

paymentGroupTypes Identifies the payment group types, such as creditCard or storeCredit.

Display Billing Page Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"init\" : \"true\", \"paymentGroupTypes\" : \"creditCard,storeCredit\"}""http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/getPaymentGroups"


{"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": "[email protected]", "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.


defaultPaymentGroupName Identifies the default payment group name.

Specify Default Payment Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"defaultPaymentGroupName\" : \"visa 1111\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/specifyDefaultPaymentGroup"

Applying Default Payment Group

The applyDefaultPaymentGroup actor-chain is used to apply the default payment group to the order and

continues on to order review.

Parameters: None

Apply Default Payment Group Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/applyDefaultPaymentGroup"


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


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


listId Identifies the payment list to initialize.

Initialize Payment List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"listId\" : \"o60003\"}" "http://localhost:8280/rest/model/atg/commerce/order/purchase/PaymentGroupActor/getCommerceIdentifierPaymentInfos"

The server response may resemble the following:

{"currentList": [ { "amount": 0, "relationshipType": "ORDERAMOUNTREMAINING", "splitQuantity": 0, "quantity": 0, "amountRemainingType": "ORDERAMOUNTREMAINING", "splitAmount": 0, "commerceIdentifier": { "id": "o60004", "priceInfo": { "amount": 5, "total": 5, "shipping": 0, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": false, "manualAdjustmentTotal": 0, "rawSubtotal": 5, "discountAmount": 0,


"adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }] }, "commerceItems": [{ "id": "ci7000008", "productDisplayName": "Gift Wrap", "returnedQuantity": 0, "priceInfo": { "quantityDiscounted": 0, "quantityAsQualifier": 0, "onSale": false, "currencyCode": "USD", "orderDiscountShare": 0, "adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }], "amount": 5, "discountable": null, "rawTotalPrice": 5, "listPrice": 5, "amountIsFinal": false, "discounted": false, "salePrice": 0 }, "state": 0, "quantity": 1, "catalogRefId": "xsku1043" }], "totalCommerceItemCount": 1 }, "amountType": "ORDERAMOUNT" }, { "amount": 0, "relationshipType": "ORDERAMOUNT", "splitQuantity": 0, "quantity": 0, "amountRemainingType": "ORDERAMOUNTREMAINING", "splitAmount": 0, "commerceIdentifier": { "id": "o60004", "priceInfo": { "amount": 5, "total": 5, "shipping": 0, "currencyCode": "USD", "tax": 0, "amountIsFinal": false, "discounted": false, "manualAdjustmentTotal": 0, "rawSubtotal": 5,


"discountAmount": 0, "adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }] }, "commerceItems": [{ "id": "ci7000008", "productDisplayName": "Gift Wrap", "returnedQuantity": 0, "priceInfo": { "quantityDiscounted": 0, "quantityAsQualifier": 0, "onSale": false, "currencyCode": "USD", "orderDiscountShare": 0, "adjustments": [{ "adjustment": 5, "quantityAdjusted": 1, "totalAdjustment": 5, "manualPricingAdjustment": null, "coupon": null }], "amount": 5, "discountable": null, "rawTotalPrice": 5, "listPrice": 5, "amountIsFinal": false, "discounted": false, "salePrice": 0 }, "state": 0, "quantity": 1, "catalogRefId": "xsku1043" }], "totalCommerceItemCount": 1 }, "paymentMethod": "visa - 1111", "amountType": "ORDERAMOUNT" }]}

Applying Multiple Payment Groups to an Order

The applyMultiplePaymentGroups actor-chain is used to apply multiple payment groups to an order.


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 CreateCreditCartActor is used to create a new credit card when working in the Billing page. The path to

this actor is: /atg/commerce/order/purchase/CreateCreditCartActor.

This actor contains the newCreditCard actor-chain:


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:


nickname The nickname of the credit card to update.

creditCardType The type of credit card to update.

creditCardNumber The credit card number to update.















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



getCurrentCatalogRootCategories Obtains the user’s current catalog and root categories.

getCategory Displays the user’s sub-categories.

getProduct Views a product by Product ID.

Getting the User’s Current Catalog

The getCurrentCatalogRootCategories actor-chain looks at the user’s profile and obtains their current

catalog and root categories.

Parameters: None

Get Current Catalog Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/catalog/ProductCatalogActor/


getCurrentCatalogRootCategories"

A typical server response may be similar to the following:

{"rootCategories": [ { "id": "rootCategory", "description": null, "defaultParentCategory": null, "displayName": "Commerce Root", "type": null }, { "id": "NonNavigableProducts", "description": "", "defaultParentCategory": null, "displayName": "Non Navigable Products", "type": null }]}

Browsing the Catalog By Category ID

The getCatagory actor-chain allows the user to browse the catalog sub-categories. The actor-chain looks for

a category using its categoryId. If the category is located, the chain checks whether the category belongs to

the user’s catalog in their current Profile, and if the item belongs to the current site. If it does, the chain returns

the category. If the category is not found using the catalogId, the chain will return an empty response. If the

category does not belong to a user’s catalog or current site, the chain will return an error message.


categoryId The ID of the category.

catalog Used by the CategoryItemLookupDroplet. If filterByCatalog is set to

true, this parameter provides the acceptable catalog.

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




catalog Used by the CategoryItemLookupDroplet. If filterByCatalog is set to true,

this parameter provides the acceptable catalog.

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"


{ "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" }], "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 ATG Commerce Reference Store 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.



productPriceRanges Provides the lowest and highest sale price for a product. These

prices are obtained from the user’s profile.

skuPrices Displays either the listPrice and salePrice for a specific

SKU if price lists are enabled. If price lists are not enabled,

displays both listPrice and salePrice.

Getting Lowest and Highest Prices for a Product

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

following parameters:


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"



{"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. It uses the

following parameters:


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"


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

Looking Up an Order by Order ID or User ID

The OrderLookupActor is used to look up the current user’s orders by order or user ID. The path to this actor is:

/atg/commerce/order/OrderLookupActor.

This actor contains the orderLookup actor-chain:


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

Lookup Order By Profile ID Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" –d"http://localhost:8280/rest/model/atg/commerce/order/OrderRepositoryActor/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}}

Cancelling or Deleting an Order

The CancelOrderActor is used to cancel or delete an order. This actor is located in: /atg/commerce/order/

purchase/CancelOrderActor.




cancelCurrentOrder Cancels or deletes the user’s current order.

cancelOrder Cancels or deletes an order.

Cancel or Delete Current Order

The cancelCurrentOrder actor-chain deletes the current order.

Parameters: None

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CancelOrderActor/cancelCurrentOrder"

Cancel or Delete a Specific Order

The cancelOrder actor-chain deletes a specified order.


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:


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":\"Save This Order\"}" "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:


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"http://localhost:8280/rest/model/atg/commerce/order/purchase/ConfirmOrderActor/confirmOrder"


{"order": { "lastModifiedTime": 1363287004602, "shippingGroupCount": 1, "paymentGroupCount": 1, "shippingGroups": [{ "specialInstructions": {}, "handlingInstructions": [], "state": 0, "locationId": null, "shippingMethod": "Ground", "id": "sg140002", "trackingNumber": null, "priceInfo": { "amount": 6.5,


"currencyCode": "USD", "amountIsFinal": false, "discounted": false, "rawShipping": 6.5 }, "description": "sg140002", "actualShipDate": null, "submittedDate": null, "shipOnDate": null, "shippingAddress": { "middleName": null, "lastName": "Smith", "ownerId": null, "state": "MA", "address1": "1 Main St", "address2": "", "address3": null, "companyName": null, "suffix": null, "city": "Cambridge", "country": "USA", "id": null, "postalCode": "02046", "faxNumber": null, "phoneNumber": "6176378687", "county": null, "email": "[email protected]", "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, "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", "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": "[email protected]", "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, which contains the following parameters:


allowEmptyOrders If set to false, will return an error if an order is commited that contains no

items.

salesChannel The sales channel used to submit the order. The values are “Web”, “Call

Center” or Scheduled Orders”, and are defined in the Order repository.

siteId The ID of the site to be recorded in the order.


Commit Order Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/order/purchase/CommitOrderActor/commitOrder"

Sending Order Confirmation

The OrderConfirmationActor is referenced by the CommitOrderActor to display confirmation of a

successfully committed order. The path to this actor is/atg/commerce/order/purchase/

OrderConfirmationActor.

This actor contains the orderConfirmation actor-chain.

Parameters: None

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


{orderId: "0132", email: [email protected]}

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 132) and Add Item From Gift List Example (page 132).

The GiftlistActor contains several actor-chains that initiate gift list actions. The path for this actor is /atg/

commerce/gifts/GiftlistActor.



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 profile’s list of gift lists.

Creating a Gift List

The createGiftlist actor-chain creates a gift list.


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.

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.



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.



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.


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.


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

removeGiftitemIds The ID of the items to remove from the gift list.

Remove Item from Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{"giftlistId": "gl20002", "removeGiftitemIds": "gi10001" }""http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/removeItemFromGiftlist"

Removing Items from a Wish List

The removeItemFromWishlist actor-chain removes an item from a wish list.



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.


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:

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.



giftlistId The ID of the gift list to delete.

Delete a Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{"giftlistId": "gl20002"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/deleteGiftlist"

Viewing the Current Profile’s List of Gift Lists

The profileGiftlist actor-chain views the current profile’s list of gift lists.

Parameters: None

View Current Profile’s List of Gift List Example

curl -v -b customer_cookies.txt -H "Content-Type: application/json" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistActor/profileGiftlists"


{"giftlists": [ { "name": "Birthday", "repositoryId": "xgl20004" }, { "name": "Anniversary", "repositoryId": "gl430003" }]}

Viewing a Gift List

The GiftlistLookupActor is used to view a customer’s gift list. This actor is located at: /atg/commerce/

gifts/GiftlistLookupActor, and contains the info actor-chain.


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"


{"giftlist": { "giftlistItems": [], "instructions": "", "description": "Upcoming birthday gifts.", "name": "Birthday", "public": true, "date": {"time": 1386521853000}, "type": "Birthday", "repositoryId": "xgl20004", "addressId": "se-980030"}

Viewing a Gift List’s Items

The GiftlistLookupActor is used to view the items within a customer’s gift list. This actor is located at: /atg/

commerce/gifts/GiftlistLookupActor, and contains the items actor-chain.


giftlistId The ID of the gift list to view.

View Gift List Item Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"giftlistId\" : \"gl430003\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/items?giftlistId=xgl10002"


{"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 }, { "repositoryId":"xgi10008", "productId":"xprod2138", "siteId":"homeSite", "skuId":"xsku2138", "quantity":1 }]}

Viewing a Wish List

The GiftlistLookupActor is used to view a customer’s wish list. This actor is located at: /atg/commerce/

gifts/GiftlistLookupActor, and contains the viewWishlist actor-chain.

Parameters: None


View Wish List Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/ viewWishlist"


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


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

Searching for a Gift List

The GiftlistSearchActor is used to find a customer’s gift list. This actor is located at: /atg/commerce/

gifts/GiftlistSearchActor, and contains the search actor-chain.


currentPage Sets the current page.

searchInput Looks for matching strings in owner.firstName or owner.lastName.



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.

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"


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

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.



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.



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"


{ "FashionIsland": { "distance": 0, "postalCode": "92660", "phoneNumber": "555-555-2006", "name": "Fashion Island", "state": "CA", "address1": "401 Newport Center Drive", "stockLevel": 0, "city": "Newport", "country": "USA" }, "BiltmoreFashionPark": { "distance": 0, "postalCode": "85016", "phoneNumber": "(555) 555-1963", "name": "Biltmore Fashion Park", "state": "AZ", "address1": "2404 East Camelback Road", "stockLevel": 0, "city": "Phoenix", "country": "USA" }}

Displaying Search Results for In-Store Pickup

The currentResultPageNum actor-chain is used to display stores that contain the specified item.



pageNum Identifies which page of the results set is being viewed. The default value

is 1, with the base value of this parameter set to1 instead of 0 for usability.

maxResultsPerPage The maximum number of results to display on the page.

Display In-Store Search Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"pageNum\":\"2\", \"maxResultsPerPage\":\"2\" }" "http://localhost:8280/rest/model/atg/commerce/locations/StoreLocatorActor/currentResultPageNum"

Identifying a State

The stateListActor is used to identify the state of a user’s profile locale. The path of this actor is /atg/

commerce/util, and it contains the states actor-chain.

The actor-chain contains the following parameters:


countryCode Identifies the country code of a specific customer.

State Identification Example

curl -L -v -b customer_cookies.txt -H "Content-Type: application/json" -d "{\"countryCode\":\"US\" }" "http://localhost:8280/rest/model/atg/commerce/util/states"


{"states":[ { "code":"AK", "displayName":"AK - Alaska" }, { "code":"AL", "displayName":"AL - Alabama" }, { "code":"AR", "displayName":"AR - Arkansas" },


...

}]}


6 Internal REST MVC Service Call Examples 175

6 Internal REST MVC Service Call

Examples

The following REST MVC services enable Call Center agents to assist customers. The following REST MVC calls

examples are specific to internal users, such as those used by Oracle ATG 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 ATG REST MVC calls for external customers, refer to

the External REST MVC Service Call Examples (page 121) section.

Internal REST MVC Service Calls Workflow Example

The following diagram shows an example of an agent’s workflow when adding an item to a cart. Each of the

REST MVC calls performs an action that propels the agent through the workflow. Note that depending on the

actions required, the process may flow differently.

176 6 Internal REST MVC Service Call Examples

This example begins with the agent logging in to the REST Server, and ends when the customer is sent an order

confirmation e-mail.

Note: The following examples are provided as guidelines for working with Internal REST MVC calls. The

responses returned by your server may vary based upon your environment’s configuration.

Getting the Session Confirmation Number

The first actor that must be invoked is the Dynamo Session Confirmation actor. As described in the Using

Dynamo Session Confirmation Numbers (page 78) section, the session confirmation number is used by

the REST Web Services to provide secure access to the REST calls. The Form Element (page 92) and The

Component Element (page 84) 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"


{"sessionConfirmationNumber":-5166444348429687167}


Logging Agents In and Out

The /atg/userprofiling/InternalProfileActor contains actor-chains that perform the following:


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.


login The login of the agent.

password The agent’s password.

doWarnings If set to true, will display warnings when changes occur.

doTicketDispositionPrompt If set to true, will display prompts when changes occur.

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.

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/userprofiling/InternalProfileActor/login"

If the log in information proves to be correct, the following success server response occurs:

{"userId": "svcUserAdmin>}

If the log in information proved to be incorrect, the following exception would occur:


{"formError": true, "formExceptions":[{"localizedMessage":"The password and logincombination is incorrect.","errorCode":"invalidPassword"}]}

Logging Out Agents

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

Parameters: None

Agent Log Out Example

curl -L -v -c agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/userprofiling/InternalProfileActor/logout"

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:


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.




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:


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.




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/agent/ui/formhandlers/TicketingActor contains the addNote actor-chain, which is used

to add a call note to a ticket in Commerce Service Center:


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 inventoryin for this product.\", "share": "false", "inbound": "true" }""http://localhost:8180/rest/model/atg/svc/ui/formhandlers/TicketingActor/addNote"


Viewing a Customer

The /atg/svc/agent/ui/formhandlers/ServiceUIProfileActor contains the viewCustomer actor-

chain:


customerId The ID of the customer to view.

View Customer Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"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 actor-chains that perform the

following:


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

CSC account when the orderId and saveCreditCards parameters are used.


firstName The first name of the new customer.

middleName The middle name or initial of the new customer.



lastName The last name of the new customer.

email The e-mail address of the new customer.

login The customer’s login.



orderId Used when creating an account. Indicates the order ID. If this property is set,

and saveCreditCards is set to true, copies the credit card information from

the order to the user’s profile. Used with CSC only.

saveCreditCards Used when creating an account. Indicates if the credit card information for the

customer should be saved. Used with CSC only.

address.address1 The first address field associated with the customer’s address.

address.address2 The second address field associated with the customer’s address.

address.city The city associated with the customer’s address.

address.companyName A company name associated with the customer’s address.

address.country A country associated with the customer’s address.

address.county A county associated with the customer’s address.

address.jobTitle A job title associated with the customer’s address.

address.postalCode The postal code associated with the customer’s address.

address.faxNumber A fax number associated with the customer’s address.

address.firstName The first name of the customer associated with the address.

address.middleName The middle name or initial of the customer associated with the address.

address.lastName The last name of the customer associated with the address.

address.phoneNumber The phone number associated with the customer’s address.

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

address.state The state associated with the customer’s address.

address.suffix A suffix associated with the customer, such as Jr.

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":\"[email protected]\", "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 CSC account based upon a customer profile by

including the orderId and the saveCreditCards parameters. This service is used specifically on the CSC Order

Completion page, once you have created and completed an order. You could use this service to create a new

user, and then copy the payment information from the order into the user’s profile:

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{"orderId":\"o99720003\", "saveCreditCards":true, "firstName":\"Bill\","middleName":\"T\", "lastName":\"Hitchock\", "email":\"[email protected]\","login":\"bill14\", "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"

Updating an Existing Customer Profile

The update actor-chain is used to update a customer profile.





email The e-mail address of the customer.


address.address1 The first address field associated with the customer’s address.

address.address2 The second address field associated with the customer’s address.

address.city The city associated with the customer’s address.

address.companyName A company name associated with the customer’s address.

address.country A country associated with the customer’s address.

address.county A county associated with the customer’s address.

address.jobTitle A job title associated with the customer’s address.



address.postalCode The postal code associated with the customer’s address.

address.faxNumber A fax number associated with the customer’s address.

address.firstName The first name of the customer associated with the address.

address.middleName The middle name or initial of the customer associated with the address.

address.lastName The last name of the customer associated with the address.

address.phoneNumber The phone number associated with the customer’s address.

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

address.state The state associated with the customer’s address.

address.suffix A suffix associated with the customer, such as Jr.

Update Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" –d"{"firstName":\"Bill\", "middleName":\"Theodore\", "lastName":\"Hitchock\","email":\"[email protected]\", "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.


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:


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.


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.

Add Customer Profile Note 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.search.routing.command.search.Field"}}, \"atg-rest-values\":[{"atg-rest-class-type":"atg.search.routing.command.search.Field", \"name\":"lastName",\"op\": "starts",\"value\": "t"} ]}}" "http://localhost:8280/rest/model/atg/svc/agent/ui/formhandlers/CustomerSearchTreeQueryActor/search"


{ "searchResponse": {"items": [ { "lastName": "Taylor", "postalCode": "89501", "phoneNumber": "2125558105", "email": "[email protected]", "profileId": "se-570105", "login": "[email protected]", "firstName": "Chuck" }, { "lastName": "Thomas", "postalCode": "59101", "phoneNumber": "2125558855", "email": "[email protected]", "profileId": "se-570056", login": "[email protected]", "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.



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.

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 actor-chains that perform the following:


addAddress Adds an address to a customer profile.

updateAddress Updates an address in a customer profile.

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.


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

Editing an Address in a Customer Profile

The updateAddress actor-chain is used to edit or update an existing address in a customer profile.


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.


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:


addCreditCard Adds a new credit card to a customer profile.

updateCreditCard Updates credit card information in a customer’s profile.

deleteCreditCard Deletes a credit card from a customer’s profile.

Adding a Credit Card to a Customer Profile

The addCreditCard actor-chain is used to add a new credit card within a customer profile.


creditCardType The type of credit card to add.


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.


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"


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


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.


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.







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


creditCardId Identifies the credit card to delete.

Delete Credit Card From Customer Profile Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"creditCardId":\"usercc99020006\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/repository/CreditCardActor/deleteCreditCard"

Viewing a Customer’s Shopping Cart

The /atg/commerce/custsvc/order/ShoppingCartActor contains a single detailed actor-chain, which

is used to view or review a customer’s cart or order, and the summary actor-chain, which provides a summary of

the shopping cart.


Parameters: None

View Customer Cart Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShoppingCartActor/detailed"


{"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": "[email protected]", "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", "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", "amount": 0, "relationshipType": "SHIPPINGQUANTITY", "returnedQuantity": 0, "shippingGroupId": "sg110004", "commerceItemId": "ci10000001", "quantity": 1 }], "totalCommerceItemCount": 1}}

Working with a Customer’s Shopping Cart

The cartModifierActor contains several actor-chains that modify the customer’s shopping cart. The path for

this actor is /atg/commerce/custsvc/order/cartModifierActor.



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.

changeSKUs Changes the SKU of one or more commerce items in

the current order.

Adding Multiple Items to a Customer’s Shopping Cart

The addMultipleItemsToOrder actor-chain is used when adding more than one item to the customer’s

shopping cart.


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"

Adding Items to a Customer’s Shopping Cart

The addItemToOrder actor-chain is used to add a single item to a customer’s shopping cart. It also is used to

add an item from a customer’s gift/wish list to a shopping cart, as well as adding an item to an in-store pickup

order:







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.


Add Item to Customer’s Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"catalogRefIds": "xsku1043","productId": "xprod1015","quantity": 1}""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addItemToOrder"

Add Item to Customer’s In-Store Pickup Example

Note the use of the locationId to identify the store from where the item will be picked up.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"catalogRefIds" : "xsku2085", "productId" : "prod10004", "locationId" :"AventuraMall", "quantity": 8}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addItemToOrder"

Add Item From Customer’s Gift List Example

Note the use of the giftlistId and the giftlistItemId.


curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"catalogRefIds" : "xsku2085", "productId" : "xprod2085", "giftlistId" : "gl40007","giftlistItemId" : "gi40001", "quantity": 1}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addItemToOrder"

Add Item From Customer’s Wish List Example

This example is similar to the Gift List example, however it uses the addToWishlist instead of the giftlistId.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"addToWishlist" : "true", "catalogRefIds" : "xsku2085", "productId" : "xprod2085","giftlistItemId" : "gi40001", "quantity": 1}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/addItemToOrder"

Updating the Customer’s Shopping Cart by SKU ID

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

This actor-chain has the following parameters:


removalCatalogRefIds The list of catalog reference IDs to remove from the order.

Update Customer’s Shopping Cart by SKU ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrder?xsku1043=2"

Updating the Customer’s Shopping Cart by Commerce ID

The setOrderByCommerceId actor-chain updates the quantities of items within the customer’s shopping cart

using the Commerce ID. Note that this actor-chain is also used to perform a price override. Refer to the Adjusting

Customer’s Orders (page 227) section for information on price overrides.

This actor-chain contains the following parameter:


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


Update Customer’s Shopping Cart by Commerce ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrderByCommerceId?ci111000001=3"

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

The setOrderByRelationshipId actor-chain is used to update the quantities of items within the customer’s

shopping cart using the CommerceItem or the shipping group relationship ID.

This actor-chain has the following parameter:


removalRelationshipIds The list of relationship IDs to remove from the order.

Update Customer’s Shopping Cart by Relationship ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrderByRelationshipId?r99090004=4"

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

The removeAndAddItemToOrder actor-chain is used to removes items from the order and then adds it to the

order.




quantity The quantity of the product.

removalCommerceIds The ID given to the item, or to a list of Commerce items, that should be removed

from the order.

Move an Item to the Customer’s Cart Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"catalogRefIds":"xsku1043","productId": "xprod1015","quantity": 1,


"removalCommerceIds":"ci116000002"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/removeAndAddItemToOrder"

Removing an Item From the Customer’s Shopping Cart

The removeItemFromOrder actor-chain removes items from the customer’s shopping cart using the commerce

ID.



removalCommerceIds The list of Commerce item IDs to remove from the order.

Remove Item From Customer’s Cart Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/removeItemFromOrder?removalCommerceIds=ci115000001"

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

The removeItemFromOrderByRelationshipId actor-chain is used to remove items from the customer’s

shopping cart using the CommerceItem or the shipping group relationship ID.



removalRelationshipIds The list of relationship IDs to remove from the order.

Remove Item From Customer’s Cart by Relationship ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/removeItemFromOrderByRelationshipId?removalRelationshipIds=r99160002"

Starting the Checkout Process with SKU ID

The moveToPurchaseInfo actor-chain starts the checkout process by verifying for changes in the order. The

current order’s SKU quantities are passed in to initiate the checkout process.


Parameters: None

Continue the Checkout Process with SKU ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/moveToPurchaseInfo?sku40051=1"

Starting the Checkout Process with Commerce ID

The moveToPurchaseInfoByCommerceId actor-chain starts the checkout process. The current order’s

commerce ID quantities are passed in to initiate the checkout process.

Parameters: None

Continue the Checkout Process with Commerce ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/moveToPurchaseInfoByCommerceId?ci4000006=1"

Starting the Checkout Process with Relationship ID

The moveToPurchaseInfoByRelId actor-chain starts the checkout process. The current order’s relationship ID

quantities are passed in to initiate the checkout process.

Parameters: None

Continue the Checkout Process with Relationship ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/moveToPurchaseInfoByRelId?r99290001=1"

Changing the SKU of an Item

The changeSkus actor-chain changes the SKU of one or more commerce items in the current order.

Parameters: To modify the SKU of an item, pass the Commerce ID prefixed by SKUCNG with the new SKU ID as

the value: SKUCNG:{CommerceItem ID}={SKU ID}

Change SKU Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/changeSkus?SKUCNG:ci115000001=2"


Assisting the Customer with the Shipping Page

The ShippingGroupActor contains several actor-chains that modify the Shipping page. The path for this actor

is /atg/commerce/custsvc/order/ShippingGroupActor.



getShippingGroups Initializes and retrieves avilable shipping groups.

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.


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"


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


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

ATG Commerce Programming Guide for further information.


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.


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.


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"

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:






address1 The first address field associated with this shipping group.

address2 The second address field 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:


nickname The nickname associated with the shipping group to update.




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.








Edit Hardgood Shipping Group Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"nickname\": \"Address\",\"firstName\": \"Jane\",\"lastName\":\"Doe\",\"address1\": \"2 Main St\",\"city\": \"Wilmington\",\"state\":\"MA\",\"country\": \"USA\",\"postalCode\": \"01887\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/UpdateHardgoodShippingGroupActor/updateHardgoodShippingGroup"

Obtaining the Customer’s Current Shipping Info List

The getAllCommerceItemShippingInfos actor-chain obtains all of the Commerce Item Shipping Info (CISI).

Note that you must call this method to initialize the shipping list prior to calling applyShippingGroups.

Parameters: None

Initialize Shipping List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/ShippingGroupActor/getAllCommerceItemShippingInfos"

Assisting the Customer with the Billing Page

The PaymentGroupActor contains several actor-chains that allow the agent to assist the customer when

working with the billing page. The path for this actor is /atg/commerce/custsvc/order/

PaymentGroupActor.



getPaymentGroups Displays the customer’s billing information.



getCommerceIdentifierPaymentInfos Gets the Commerce Identifier Payment Info (CIPI).

applyMultiplePaymentGroups Applies multiple payment groups.

claimItem Used to claim store credit or a gift card.

Display the Customer’s Payment Groups

The getPaymentGroups actor-chain is used to display the customer’s payment groups.


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"


{"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": "[email protected]", "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.


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



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 "{"claimCode": "sc36b60" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/PaymentGroupActor/claimItem"

Claiming a Customer’s Coupon

The CouponActor is used by a customer to claim a coupon. It is located in: /atg/commerce/

custsvc/promotion/CouponActor.

This actor has the claimCoupon actor-chain:


couponClaimCode The coupon code that is being provided by the customer.

Claim Customer’s Coupon Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"couponClaimCode":"TENSHIP" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/promotion/CouponActor/claimCoupon"

Applying Multiple Payment Groups

The applyMultiplePaymentGroups actor-chain is used to apply multiple payment groups to a customer’s

order. Once the payment groups are applied, the process continues on to Order Review.


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":"atg.commerce.order.purchase.CommerceIdentifierPaymentInfo", \"amount\" :\"5.00\", \"creditCardVerificationNumber\" : \"1234\"}]}}""http://localhost:8280/rest/model/atg/commerce/custsvc/order/PaymentGroupActor/applyMultiplePaymentGroups"

Working with Credit Cards Within an Order

The /atg/commerce/custsvc/order/CreateCreditCardActor contains actor-chains that allow an agent to

work with the customer’s credit card information while working on an order:


getExistingAddresses Initializes the existing addresses in an order.

newCreditCardWithExistingAddress Creates a new credit card payment group with an existing

address in an order.

newCreditCardWithNewAddress Creates a new credit card payment group with a new address

in an order.

Getting a Customer’s Existing Address

The getExistingAddress actor-chain is used to initialize the existing address of the customer. This actor-chain

must be run prior to using the newCreditCardWithExistingAddress actor-chain.

Properties: None

Initialize Customer Existing Address Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CreateCreditCardActor/getExistingAddresses"


Adding a Credit Card to an Existing Address in an Order

The newCreditCardWithExistingAddress actor-chain is used to create a new credit card payment group

with an existing address in an order. Note that the getExistingAddress actor-chain must be run prior to

running this call.


creditCardType Identifies the address to delete.

creditCardNumber Adds the new credit card number.

expirationMonth Adds the new credit card’s expiration month.

expirationYear Adds the new credit card’s expiration year.

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.


creditCardType Identifies the address to delete.

creditCardNumber Adds the new credit card number.

expirationMonth Adds the new credit card’s expiration month.

expirationYear Adds the new credit card’s expiration year.

firstName Identifies the first name of the customer associated with this billing address.

middleName The middle name or initial of the customer associated with this billing address.

lastName The last name of the customer associated with this billing address.









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/order/purchase/UpdateCreditCardActor.

This actor contains the updateCreditCard actor-chain:


nickname The nickname of the credit card to update.

creditCardType The type of credit card to update.

creditCardNumber The credit card number to update.



generateNickname Used to generate a new nickname for 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.

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"


{"profile": { "middleName": null, "lastName": "Smith", "expressCheckout": false, "defaultCreditCard": null, "orderPriceLimit": null, "locale": null, "currentLocation": "unknown", "id": "220022", "registrationDate": {"time": 1363218368049}, "email": "[email protected]", "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" }}}}

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.



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.

Clearing Search Sessions

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"

Searching for Orders

The search actor-chain searches for orders and configures the result display. It contains the following

parameters.


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

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

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.search.routing.command.search.Field"}}, \"atg-rest-values\":[{"atg-rest-class-type":"atg.search.routing.command.search.Field", \"name\":"orderId",\"op\": "starts",\"value\": "x"} ]}}" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/OrderSearchTreeQueryActor/search"


{ "searchResponse": {"items": [


{ "total": 715.2, "lastName": "johnson", "returnedQuantity": 2, "status": "no_pending_action", "originOfOrder": "default", "submittedDate": "1340638926", "quantity": 4, "firstName": "Brandon", "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, "lastName": "Moore", "returnedQuantity": 0, "status": "processing", "originOfOrder": "default", "submittedDate": "1340636993", "quantity": 2, "firstName": "Lindsay", "orderId": "xco20031" } ]}, "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:


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.


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.



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:


orderIdToCancel The ID of the order to cancel.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"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"


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

The CommitOrderActor saves or persists an order. It is located in: /atg/commerce/custsvc/

order/CommitOrderActor.

The CommitOrderActor has the persistOrder actor-chain that 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"

Committing a Customer’s Order

The CommitOrderActor is used to commit the order. The path to this actor is: /atg/commerce/custsvc/

order/CommitOrderActor.

This actor contains the commitOrder actor-chain.

Parameters: None

Commit Customer’s Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CommitOrderActor/commitOrder"

Confirming a Customer’s Order

The ConfirmOrderActor is used to confirm a customer’s order. As it does this, it re-prices the order one last

time before the agent commits the order to ensure that all pricing is up to date. The path to this actor is: /atg/

commerce/pricing/ConfirmOrderActor.

This actor contains the confirmOrder actor-chain.

Parameters: None

Confirm Customer’s Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/ConfirmOrderActor/confirmOrder"


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

Adding a Note to a Customer’s Current Order

The OrderNoteActor is used to add a note to a customer’s current order. The path to this actor is: /atg/

commerce/custsvc/order/OrderNoteActor/addOrderNote.

This actor contains the addOrderNote actor-chain.



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 comes available\" }""http://localhost:8180/rest/model/atg/commerce/custsvc/order/OrderNoteActor/addOrderNote"

Adding a Note to a Customer’s Original Order

The OriginalOrderNoteActor is used to add a note to a customer’s original order. The path to this actor is: /

atg/commerce/custsvc/order/OriginalOrderNoteActor.

This actor contains the addOrderNote actor-chain.


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"

Adjusting Customer’s Orders

The following REST services allow an agent to make manual price adjustments to an order, and to initiate a price

override.

The ManualAdjustmentsActor is used to make a price adjustment to a customer’s order. The path to this actor

is: /atg/commerce/custsvc/order/ManualAdjustmentsActor.




addAdjustment Used to issue a manual adjustment to an order.

delteAdjustment Used to delete an adjustment from an order.

Adjusting a Customer’s Order

This actor contains the addAdjustment actor-chain. This actor-chain is used to issue an adjustment to a

customer’s order.


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.

adjustmentType The type of adjustment.

Adjust Order Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"adjustmentAmount" : "10", "adjustmentReasonCode" : "Appeasement","adjustmentNote" : \"Customer ordered 10 of these last week\", "adjustmentType" :"amountOff" } "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ManualAdjustmentsActor/addAdjustment"

Deleting an Adjustment from a Customer’s Order

This actor contains the deleteAdjustment actor-chain. It is used to delete an existing adjustment from an

order.


adjustmentId The ID of the adjustment.

adjustmentReasonCode The adjustment reason code used for this adjustment.

Delete Order Adjustment Example

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


"adjustmentId" : "700001" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/order/ManualAdjustmentsActor/deleteAdjustment"

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

The CartModifierActor contains the setOrderByCommerceId actor-chain that allows an agent to override

the price of an item within an order.

To override a price, add the following to the URL:

IPO:commerceItemId=newPrice

Override Price Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/setOrderByCommerceId?ci172000006=1&IPO:ci172000006=19.99"

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.



getCurrentCatalogRootCategories Obtains the user’s current catalog and root categories.

getCategory Displays the user’s sub-categories.

getProduct Views a product by Product ID.

Getting the Customer’s Current Catalog

The getCurrentCatalogRootCategories actor-chain obtains the current catalog.

Parameters: None

Get Current Catalog Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/commerce/custsvc/catalog/


ProductCatalogActor/getCurrentCatalogRootCategories"

The server response might be:

{"rootCategories": [ { "id": "homeStoreNonNavigableProducts", "description": "", "defaultParentCategory": null, "displayName": "Non Navigable Products", "type": null }, { "id": "homeStoreRootCategory", "description": null, "defaultParentCategory": null, "displayName": "Home Store Root", "type": null }]}

Browsing the Customer’s Catalog By Category ID

The getCatagory actor-chain allows the agent to browse the customer’s current catalog by category ID.


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.

siteIds The site associated with the catalog.

catalogs Identifies the catalogs to browse.

Browse by Catalog ID Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"categoryId\" : \"cat50056\" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/catalog/ProductCatalogActor/getCategory"

Browsing the Customer’s Catalog By Product ID

The getProduct actor-chain allows the agent to browse the customer’s current catalog and to look up products

by their ID.




filterBySite Identifies if the product is contained in the current site, and if so filters by site.

filterByCatalog Identifies if the product is contained in the current site, and if so filters by catalog.

siteIds The site associated with the catalog.

catalogs Identifies the catalogs to browse.

Get Product by Product ID Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"productId\" : \"xprod1047\"}" "http://localhost:8280/rest/model/atg/commerce/custsvc/catalog/ProductCatalogActor/getProduct"

Search a Catalog

The catalog search REST call uses Endeca catalog search. For information on Endeca catalog searches, refer to

the ATG Commerce Reference Store Installation and Configuration Guide.

Note: When a CSC agent performs a search, the agent’s profile is the current profile, but when ATG 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"

Working with Customer’s Gift Lists

The following actors are used to work with a customer’s gift or wish list. For information on adding a gift or wish

list item to a shopping cart, refer to Add Item From Customer’s Gift List Example (page 198) and Add Item

From Customer’s Wish List Example (page 199).

The CSRGiftlistActor contains several actor-chains that initiate gift list actions. The path for this actor is /

atg/commerce/gifts/GiftlistActor.



createGiftlist Creates a gift or wish list.



updateGiftlist Updates a gift or wish list.

addItemToGiftlist Adds an item to a gift list.

removeItemFromGiftlist Removes an item from a gift list.

addItemToWishlist Adds an item to a wish list.

removeItemFromWishlist Removes an item from a wish list.

moveItemsFromCart Removes a gift or wish list item from the Shopping Cart.

deleteGiftlist Deletes a gift or wish list.

Creating a Customer’s Gift or Wish List

The createGiftlist actor-chain creates a gift list or a wish list.

Note: The following parameters are all optional, unless stated otherwise.



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.





isNewAddress Identifies if the address included in this list is new.




address1 The first address field of the customer.



address2 The second address field of the customer.

city The city of the customer’s address.

state The state or province of the customer’s address.

postalCode The postal code of the customer’s address.

country The country of the customer’s address.

phoneNumber The phone number associated with the customer.

Basic Create Gift List Example

This example uses only the required parameters.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"eventName" : "Wedding", "eventType": "Wedding", "eventDate" : \"AUG 30, 2013\" }""http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/createGiftlist"

Create Gift List with Existing Address Example

This example uses an existing customer address. The address is identified by the shippingAddressId

parameter.

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"eventName" : "Birthday", "eventType": "Birthday", "eventDate" : \"AUG 30, 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, 2013\","isNewAddress" : "true", "firstName":"Tara", "lastName":"Nolan", "middleName":"C", "address1":"\101 First St\", "address2":null, "city":"Cambridge","state":"MA","country":"USA", "postalCode": "02146", "phoneNumber":"617-637-8687" }" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/createGiftlist"

Updating a Customer’s Gift or Wish List

The updateGiftlist actor-chain allows an agent to edit a customer’s gift or wish list.


Note: The following parameters are all optional, unless stated otherwise.




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.





isNewAddress Identifies if the address included in this list is new.




address1 The first address field of the customer.

address2 The second address field of the customer.

city The city of the customer’s address.

state The state or province of the customer’s address.

postalCode The postal code of the customer’s address.

country The country of the customer’s address.

phoneNumber The phone number associated with the customer.

Update Customer Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"giftlistId": "gl240010", "eventName" : "|St Patricks Day|", "eventType": "Other","description": \"Things needed for St Patrick's Day\", "eventDate" : \"MAR 17, 2013\"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/updateGiftlist"


Adding Items to a Customer’s Gift List

The addItemToGiftlist actor-chain allows an agent to add an item to a customer’s gift list.



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

Adding Items to a Customer’s Wish List

The addItemToWishlist actor-chain allows an agent to add an item to the active customer’s wish list.



quantity The quantity of the products to add to the wish list.

productId The product ID of the product to add to the wish list.

catalogRefIds The catalog reference ID of the product being added to the wish list.

Add Item to Customer’s Wish List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"productId": "xprod2085", "catalogRefId" : "xsku2085", "quantity": "1", "siteId":"homeSite" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/addItemToWishlist"


Removing Items from a Customer’s Gift List

The removeItemFromGiftlist actor-chain allows an agent to remove an item from a customer’s gift list.


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

giftitemId The ID of the item to remove from the gift list.

Remove Item from Customer’s Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"giftlistId": "gl380011", "giftItemId" : "gi30002"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/removeItemFromGiftlist"

Removing Items from a Customer’s Wish List

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


giftitemId The ID of the items to be reomved from the wish list.

Remove Item from Customer’s Wish List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"giftItemId" : "gi30001" }" "http://localhost:8280/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/removeItemFromWishlist"

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

The moveItemsFromCart actor-chain allows an agent to take an item from a shopping cart and move it into the

specified gift or wish list. You can specify a default quantity for an item, or specify the quantity for a specific item.


giftlistId The ID of the gift or wish list to which the items will be moved.



itemIds The IDs of the items to move to the list.

quantity The quantity of the items to move to the list.

Move Item to Gift or Wish List from Customer’s Cart Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"giftlistId" : "gl620010", "itemIds": "ci42000001"}" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/moveItemsFromCart?ci42000001=6"

Deleting a Customer’s Gift List

The deleteGiftlist actor-chain allows an agent to delete a specific gift list.


giftlistId The ID of the gift or wish list to delete.

Delete a Customer’s Gift List Example

curl -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{"giftlistId": "gl220010" }" "http://localhost:8180/rest/model/atg/commerce/custsvc/gifts/CSRGiftlistActor/deleteGiftlist"

Viewing a Customer’s Gift List

The GiftlistLookupActor enables an agent to view a customer’s gift or wish list. This actor is located at: /

atg/commerce/gifts/GiftlistLookupActor, and contains the following actor-chains.


view Views the ID of the customer’s gift or wish list.

giftlistItems Displays the items within the gift list.

The view actor-chain contains the following parameter:



giftlistId The ID of the gift or wish list to view.


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"


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


giftlistId The ID of the gift or wish list to view.


curl -L -v -b agent_cookies.txt -H "Content-Type: application/json" -d "{\"giftListId\" : \"gl430003\"}" "http://localhost:8280/rest/model/atg/commerce/gifts/GiftlistLookupActor/giftlistItems"

Viewing a Customer’s Wish List

The ServiceCustomerProfileActor enables an agent to view a customer’s gift or wish list. This actor is

located at /atg/userprofiling/ServiceCustomerProfileActor, and contains the viewWishlist actor-

chain.

Parameters: None


View Gift or Wish List Example

curl -L -v -b agent_cookies.txt -H "Content-Type: application/json""http://localhost:8280/rest/model/atg/userprofiling/ServiceCustomerProfileActor/viewWishlist"

Searching for a Customer’s Gift List

The GiftlistSearchActor is used to find a customer’s gift list. This actor is located at /atg/commerce/

gifts/GiftlistSearchActor, and contains the search actor-chain.




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.

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"


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

Viewing a List of Customer’s Gift or Wish Lists

The GiftlistTableActor allows an agent to display a list of all of the customer’s gift or wish lists. This actor is

located at /atg/commerce/custsvc/gifts/GiftlistTableActor, and contains the list actor-chain.


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.

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

Assisting Customers with In-Store Pickup

The REST MVC service calls that agents use to assist customer with in-store pickup are similar to the external-

based REST calls. Refer to the Working with In-Store Pickup (page 170) 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"

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""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": "ATG 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 ATG Multisite Administration Guide. The path for this actor is /atg/

dynamo/droplet/multisite/SiteGroupsActor.

Parameters: None.

List Available Sites Example

curl -x 127.0.0.1:8888 -L -v -b agent_cookies.txt -H "Content-Type:application/json" "http://localhost:8280/rest/model/atg/dynamo/droplet/multisite/SiteGroupsActor/getSites"

This REST service call returns a server response similar to the following, providing a list of sites:

{ "groupedSites": [ { "id": "storeSiteUS", "name": "ATG Store" }, { "id": "homeSite", "name": "ATG 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.



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.



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

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

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

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

 <input name="confirmURL" value="${confirmURL != null ? confirmURL : '/model/atg/commerce/custsvc/environment/ChangeOrderActor/ changeOrder-confirm'}"/>

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

<actor-chain id="changeOrder-confirm" transaction="TX_SUPPORTS"> <component id="fh" name="/atg/commerce/custsvc/environment/ChangeOrder" component-var="fh"> <output id="allWarnings" name="allWarnings" value="${fh.environmentChangeState.allWarnings}"/> <output id="isActiveTicketDisposition" name="activeTicketDisposition" value="${fh.environmentChangeState.processActiveTicketDisposition}" /> </component> <droplet id="shouldDiscardTicket" name="/atg/ticketing/droplet/ ShouldDiscardTicket" var="shouldDiscardTicketParamStack"> <input name="immediately" value="false" /> <input name="ticket" value="${nucleus['/atg/svc/agent/environment/ EnvironmentTools'].activeTicket}" /> <oparam name="output"> <output id="isDiscardable" name="isDiscardable" value="${shouldDiscardTicketParamStack.isDiscardable}" /> </oparam> </droplet></actor-chain>

<actor-chain id="error" transaction="TX_SUPPORTS"> <component id="fh" name="/atg/commerce/custsvc/environment/ChangeOrder" component-var="fh"> <output id="formError" name="formError" value="${fh.formError}"/> <output id="formExceptions" name="formExceptions" value="${fh.formExceptions}" filter-id="detailed"/> </component></actor-chain>


Part II. Legacy REST Web ServicesThis section provides information about and instructions for using the legacy Oracle ATG Web Commerce Representational

State Transfer (REST) Web Services.

The Legacy REST Web Services provide access to Nucleus components. Nucleus components are server-side JavaBeans and

servlets that perform the back-end functionality of a Web application—for example, enabling database connectivity, logging,

scheduling, and handling HTTP requests. The Oracle ATG Web Commerce platform REST Web Services expose methods that

get component data and get and set component property values. You cannot use the Oracle ATG Web Commerce platform

REST Web Services to delete components.

Note: The Oracle ATG Web 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, “ATG REST MVC Web Services” (page 75) section. The Legacy REST API is limited in its ability to be configured and is not

extensible.

7 Using Legacy REST Web Services 251

7 Using Legacy REST Web Services

This section provides general information about and instructions for using the Oracle ATG Web Commerce

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 ATG Web 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 272) and Invoking Legacy REST Component Methods (page 274).

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/

252 7 Using Legacy REST Web Services

You can address specific repository items and get or set repository item property values. Include the names

of repository items and values in the application path. Separate the names and values with a forward slash

as if it were a separate container. For example, the following URL addresses the user repository item in the

ProfileAdapterRepository repository.

http://servername:port/rest/repository/atg/userprofiling/ProfileAdapterRepository/user

The following URL addresses a specific user record in the user repository item. The value of the id property at

the end of the path indicates which user.

http://servername:port/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/210002

The following URL addresses a specific property of a user record in the user repository item.

http://servername:port/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/210002/login

See information about performing operations with repositories in Working with Repositories in Legacy

REST (page 283).

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

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.

ATG Clients for the Legacy REST Web Services

Oracle ATG Web Commerce 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 309).


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 ATG Web Commerce Service

Center. See specific procedures with examples in Logging In as an External User (page 253) and Logging In as

an Internal User (page 254).

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 253) and Logging In as an Internal User (page 254)

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

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)


* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8280 (#0)> POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8280> Accept: */*> Content-Type: application/xml> Content-Length: 71>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Added cookie JSESSIONID="7978B952714AB08BEB006A348A25ADB0" for* domain myserver, path /, expire 0< Set-Cookie: JSESSIONID=7978B952714AB08BEB006A348A25ADB0; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=* Added cookie DYN_USER_ID="120001" for domain myserver, path /, expire 1290872360< Set-Cookie: DYN_USER_ID=120001; Expires=Sat, 27-Nov-2010 15:39:20 GMT; Path=/* Added cookie DYN_USER_CONFIRM="bca3eb6c2cdeb0e4a625c7165a088e2e" for domainmyserver, path /, expire 1290872360< Set-Cookie: DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e;Expires=Sat, 27-Nov-2010 15:39:20 GMT; Path=/< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Thu, 28 Oct 2010 15:39:20 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>120001</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Specifying a Profile Realm

Include the pushRealm URL query parameter to specify a profile realm while you are logging in to the Legacy

REST Web Services interface. Include the identifier of the profile realm as the value of the pushRealm parameter.

See information about profile realms in the ATG Multisite Administration Guide. See information about the

pushRealm parameter in the ATG 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 257) and Invoking Legacy REST Form Handlers (page 275).


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

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

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> Host: myserver:8280


> Accept: */*> Content-Type: application/json> Content-Length: 70>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Added cookie JSESSIONID="09FA8F5B4B8A4C1A1E97480A91BA7EB8" for domain myserver,path /, expire 0< Set-Cookie: JSESSIONID=09FA8F5B4B8A4C1A1E97480A91BA7EB8; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAsU2VhcmNoLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWFyY2hBZG1pbkxpY2Vuc2UvMCBQdWJsaXNoaW5nTGljZW5zZS8wIEIyQ0xpY2Vuc2UvMCAgXQ==< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Thu, 28 Oct 2010 20:57:22 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Logging Out

Users end their Legacy REST Web Services session by logging out. Once logged out, no client will be able to

perform Legacy REST Web Services operations using the session ID that was presented with the log out request.

Invoke the /atg/userprofiling/ProfileServices.logoutUser method to log out of the Legacy REST

Web Services server. Use the HTTP POST method.

The following example shows an HTTP request to log out of a Legacy REST Web Services session.

curl -v -b cookies.txt -X POST \http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/logoutUser

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/userprofiling/ProfileServices/logoutUser HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=120001; JSESSIONID=51B1124DFFC8293CF42ACA8AF2D88324;> DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=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 272)

• Invoking Legacy REST Component Methods (page 274)

• Working with Repositories in Legacy REST (page 283)

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

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


public String loginUser(String pLogin, String pPassword) throws ServletException

The Legacy 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, see XML Parameter Markup in ATG REST Services (page 67).

• JSON, see JSON Parameter Markup in ATG REST Services (page 67).

• URL query string, see URL Query String Parameter Markup (page 68).

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

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.

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

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.

Legacy REST Input Values

This section provides information about the way the Legacy REST Web Services server expects to receive

parameter values.

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.

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']}" \http://myserver:7003/rest/bean/atg/MyDog/tricks?atg-rest-json-input=true

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.

curl -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40050,/atg/commerce/gifts/Giftlists/gift-list/gl40052</arg1></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/giftlists

Note: The Legacy REST Web Services server is configured to append values to repository item properties that

accept multiple values by default. The appendMultiValuesByDefault configuration property controls this

behavior for repository item properties. If you have reconfigured this setting, set the atg-rest-append-

multi-values control parameter to true for each Legacy REST Web Services request that should append the

new value.

Replacing Multiple Values in a Repository Item Property

To replace all the existing values in a repository item property that holds multiple values, include the atg-rest-

append-multi-values control parameter with your Legacy REST Web Services request. Set the value of the

control parameter to false.

Note: You can only use the rest-append-multi-values control parameter with repository item properties. It

does not affect the way you can update non-repository properties.

The following example replaces all the values that are currently in a repository item property that holds multiple

values. Only the repository item reference that is in the functional parameter will remain in the property.

curl -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40049</arg1></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/giftlists?atg-rest-append-multi-values=false

JSON Markup Input for Multiple Value Repository Item Properties

If you are setting multiple values in a repository item property, you can use standard JSON markup for the

collection or map value. Include the atg-rest-json-input with your Legacy REST Web Service request and

set its value to true.

You can include JSON markup for multiple values in any input format. The following example shows a Legacy

REST Web Services request that includes a JSON collection in an XML message body parameter.

curl.exe -v -b cookies.txt -X POST \


-H "Content-Type: application/xml" \-d "<parameters><arg1>[ "/atg/commerce/gifts/Giftlists/gift-list/gl40050","/atg/commerce/gifts/Giftlists/gift-list/gl40052" ]</arg1></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/giftlists?atg-rest-json-input=true

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

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


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:--> name: Young--> primary key: Young__grouprole</element> <element>- RepositoryItemGroupRole:--> name: WomenOnly--> primary key: WomenOnly__grouprole


</element> <element>- RepositoryItemGroupRole:--> name: Fashionista--> primary key: Fashionista__grouprole</element> <element>- RepositoryItemGroupRole:--> name: MenOnly--> primary key: MenOnly__grouprole</element> <element>- RepositoryItemGroupRole:--> name: ThirtySomethings--> primary key: ThirtySomethings__grouprole</element> </roles>


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

The following example shows a Legacy REST Web Services request that includes the atg-rest-user-input

control parameter.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-user-input=MyMessageId001

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-user-input=MyMessageId001 HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: JSESSIONID=AD84270CB05CC0960580D1B875595822>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: application/json;charset=UTF-8


< 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

268).

You can configure the default setting for atg-rest-show-rest-paths.

The example below shows a REST path in the creditCards property. The example that follows it shows the

effect of the atg-rest-show-rest-paths control parameter.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="A2C79A00F7194A1F113604FD1C4BE7DD" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=A2C79A00F7194A1F113604FD1C4BE7DD; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 05 Nov 2010 21:50:44 GMT


<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>


<creditCards>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/130001/creditCards</creditCards>


</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

The example below shows a collection value that has been expanded. The Legacy REST Web Services request

sets the atg-rest-show-rest-paths control parameter to false.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/?atg-rest-show-rest-paths=false

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/?atg-rest-show-rest-paths=false HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="9D730DE9D4A7C250994F20363ACC3FA6" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=9D730DE9D4A7C250994F20363ACC3FA6; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 05 Nov 2010 22:04:32 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>


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


</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Collection Values in Output

The Legacy REST Web Services server will return each element in a property value of class

java.utils.Collection as shown in the examples below.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/userprofiling/ProfileUserDirectory/roles

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/bean/atg/userprofiling/ProfileUserDirectory/roles HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="6F710DD421CDBB1C0A092133210E7A0E" for* domain myserver, path /, expire 0< Set-Cookie: JSESSIONID=6F710DD421CDBB1C0A092133210E7A0E; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Wed, 03 Nov 2010 15:05:19 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <roles> <element>- RepositoryItemGroupRole:


--> name: Young--> primary key: Young__grouprole</element> <element>- RepositoryItemGroupRole:--> name: WomenOnly--> primary key: WomenOnly__grouprole</element> <element>- RepositoryItemGroupRole:--> name: Fashionista--> primary key: Fashionista__grouprole</element> <element>- RepositoryItemGroupRole:--> name: MenOnly--> primary key: MenOnly__grouprole</element> <element>- RepositoryItemGroupRole:--> name: ThirtySomethings--> 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


< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="F60503E5A6051C18D119B6CE470F9591" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=F60503E5A6051C18D119B6CE470F9591; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Wed, 03 Nov 2010 16:12:57 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <creditCards> <element> <key>MyOtherCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/credit-card/usercc10003</value> </element> <element> <key>MyCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/credit-card/usercc10001</value> </element> </creditCards></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0


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


< HTTP/1.1 200 OK< Date: Thu, 13 Oct 2011 16:18:22 GMT< Transfer-Encoding: chunked< Content-Type: application/xml; charset=UTF-8< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=* Replaced cookie JSESSIONID="V9TCTXPTkCnXrgJJKb2bhbzHwpvn2yzlDJb4JTXhLlkyw22J7xm7!-249339435" for domain12.34.567.890, path /, expire 0< Set-Cookie: JSESSIONID=V9TCTXPTkCnXrgJJKb2bhbzHwpvn2yzlDJb4JTXhLlkyw22J7xm7!-249339435; path=/; HttpOnly< X-Powered-By: Servlet/2.5 JSP/2.1<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <previousPasswords>

<element>17d0b74864b89840e07f08f46dd72f90fed59b62d476639c25667a3b3f74bdf5 </element>

<element>914eb28cb2996739bdd33ed74deed1005ff1fd40489583d22bd35d5a8344fa6c </element> </previousPasswords></atgResponse>* Connection #0 to host 12.34.567.890 left intact* Closing connection #0


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


<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 268). If you do not want to expand date properties, you can suppress

property expansion for them. See Suppressing Property Expansion in Legacy REST (page 297).

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.


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

Problems Performing Operations

If the Legacy REST Web Services server can process the input in your request but it encounters problems

performing an operation it will return HTTP status code 400 Bad Request.

The following example shows an exception that has been returned by the Legacy REST Web Services

server. HTTP status code 400 Bad Request indicates that the server cannot perform the requested

action because of a problem with the input provided. The server includes the name of the exception

(atg.beans.PropertyNotFoundException) in the message body of the response.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/dynamo/Configuration/fakeProperty

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/bean/atg/dynamo/Configuration/fakeProperty HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: JSESSIONID=67B1EAF58CC556CE7C628CDE6F395FB4>< HTTP/1.1 400 Bad Request< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: text/html;charset=utf-8< Content-Length: 1585< Date: Fri, 22 Oct 2010 19:48:53 GMT< Connection: close<<html><head><title>JBoss Web/2.1.3 Error report</title><style></style> </head><body><h1>HTTP Status 400 atg.beans.PropertyNotFoundException:Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration</h1><HR size="1" noshade="noshade"><p><b>type</b> Statusreport</p><p><b>message</b> <u>atg.beans.PropertyNotFoundException: Can't findproperty named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can'tfind property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration</u></p><p><b>description</b> <u>The request sent by the client was syntacticallyincorrect (atg.beans.PropertyNotFoundException: Can't find property named:


fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find propertynamed: fakeProperty in class: atg.service.dynamo.DAFConfiguration).</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3></body></html>* Closing connection #0

Problems Processing a Request

If the Legacy REST Web Services server cannot process the input in your request it will return HTTP status code

500 Internal Server Error.

The following example shows an exception that has been returned by the Legacy REST Web Services

server. HTTP status code 500 Internal Server Error indicates that the server cannot process the

request because of a problem interpreting the input. The server includes the name of the exception

(org.dom4j.DocumentException) in the message body of the response.

curl -v -c cookies.txt -X POST \-H "Content-Type: application/xml" -d "This is not XML." \http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Content-Type: application/xml> Content-Length: 16>< HTTP/1.1 500 Internal Server Error< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Added cookie JSESSIONID="24C3CC9056EA3A1B62DD2002DEDFAA7F" for domain myserver,path /, expire 0< Set-Cookie: JSESSIONID=24C3CC9056EA3A1B62DD2002DEDFAA7F; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: text/html;charset=utf-8< Content-Length: 1776< Date: Wed, 27 Oct 2010 18:15:29 GMT< Connection: close<<html><head><title>JBoss Web/2.1.3 Error report</title><style></style> </head><body><h1>HTTP Status 500 org.dom4j.DocumentException: Error online 1 of document : Content is not allowed in prolog. Nested exception:Content is not allowed in prolog. Error on line 1 of document : Content is notallowed in prolog. Nested exception: Content is not allowed in prolog.</h1><HR size="1" noshade="noshade"><p><b>type</b> Status report</p><p><b>message</b>


<u>org.dom4j.DocumentException: Error on line 1 of document : Content is notallowed in prolog. Nested exception: Content is not allowed in prolog. Error online 1 of document : Content is not allowed in prolog. Nested exception: Contentis not allowed in prolog.</u></p><p><b>description</b> <u>The server encounteredan internal error (org.dom4j.DocumentException: Error on line 1 of document :Content is not allowed in prolog. Nested exception: Content is not allowed inprolog. Error on line 1 of document : Content is not allowed in prolog. Nestedexception: Content is not allowed in prolog.) that prevented it from fulfillingthis request.</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3></body></html>* Closing connection #0

Working with Legacy REST Components

This section provides instructions for the Legacy REST Web Services operations involving Nucleus component

properties.

Getting Legacy REST Component Properties

To get the value of a Nucleus component property, send a Legacy REST Web Services request as described in the

following table.

Request Component Value

HTTP Method GET

Functional Parameters None

URL Include the component pathname in the application path after /rest/

bean/. Include the name of the property at the end of the path. See Nucleus

Components (page 251).

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


> Cookie: JSESSIONID=8DC60C0801D934F472BD9BE8A15A54F9>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 25 Oct 2010 21:29:05 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <httpPort>8080</httpPort></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

The following example shows a Legacy REST Web Services request that returns all the properties of a Nucleus

component.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/bean/atg/dynamo/Configuration

Setting Legacy REST Component Properties

To set the value of a Nucleus component property, send a Legacy REST Web Services request as described in the

following table.


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


bean/. Include the name of the property at the end of the path. See Nucleus


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


http://myserver:8080/rest/bean/atg/userprofiling/passwordchecker/PasswordRuleChecker/enabled

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/userprofiling/passwordchecker/PasswordRuleChecker/enabled HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: JSESSIONID=7205768051AC55AAFD5020D8931C71A7> Content-Type: application/xml> Content-Length: 43>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Tue, 26 Oct 2010 14:58:28 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>true</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Invoking Legacy REST Component Methods

To invoke a Nucleus component method, send a Legacy REST Web Services request as described in the following

table.


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


bean/. Include the name of the method at the end of the path. See Nucleus


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.


curl -v -b cookies.txt -X POST \-H "Content-Type: application/xml" \-d "<parameters><arg1>130001</arg1></parameters>" \http://myserver:8080/rest/bean/atg/commerce/order/OrderManager/getOrderCountForProfile

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/commerce/order/OrderManager/getOrderCountForProfile HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=120001; JSESSIONID=7C4C04BFDA404FA7D9443A820F32BE0D;DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e> Content-Type: application/xml> Content-Length: 44>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Wed, 27 Oct 2010 17:17:33 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse>2</atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Invoking Legacy REST Form Handlers

To invoke a Nucleus form handler, send a Legacy REST Web Services request as described in the following table.


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

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


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":"[email protected]", "value.password":"mypassword","value.confirmPassword":"mypassword", "value.firstName":"Severe","value.lastName":"Heroux" }" \http://myserver:8080/rest/bean/atg/store/profile/RegistrationFormHandler/create

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/bean/atg/store/profile/RegistrationFormHandler/create HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=1DEDBDEE3BF322FA71AFE89438DCCF9E;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b> Content-Type: application/json> Content-Length: 147>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=* Replaced cookie DYN_USER_ID="140003" for domain myserver, path /,expire 1291317542< Set-Cookie: DYN_USER_ID=140003; Expires=Thu, 02-Dec-2010 19:19:02 GMT; Path=/* Replaced cookie DYN_USER_CONFIRM="1231cf3e7573bf936dbd29dbbbfe150b" fordomain myserver, path /, expire 1291317542< Set-Cookie: DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b; Expires=Thu,02-Dec-2010 19:19:02 GMT; Path=/< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Tue, 02 Nov 2010 19:19:02 GMT<<?xml version="1.0" encoding="UTF-8"?>


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


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":"[email protected]", "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 277).

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


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>


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

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


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 ATG Web 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 ATG 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 280).

To invoke a JSP, send a Legacy REST Web Services request as described in the following table.


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 ATG Web 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 280).

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 ATG Web 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 280).

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 280). The code of the JSP itself is shown in Example Legacy REST Web Services

JSP (page 282).

$ curl -v -b cookies.txt -X GET http://myserver:7003/rest/service/atg/AnyComponent/xprod2083,foo


* About to connect() to myserver port 7003 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 7003 (#0)> GET /rest/service/atg/AnyComponent/xprod2083,foo HTTP/1.1> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5> Host: myserver:7003> Accept: */*> Cookie: JSESSIONID=tGD0P6WBTGp62dd5QczJjM0JhpMSvzQvqMbC9jvMNhJ8fS3w33vD!-531422523; DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001>< HTTP/1.1 200 OK< Date: Tue, 14 Feb 2012 18:17:34 GMT< Content-Length: 127< Content-Type: application/json< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=< X-Powered-By: Servlet/2.5 JSP/2.1<

{"displayName":"Wine Glass Set","someString":"foo"}

* Connection #0 to host myserver left intact* Closing connection #0

Legacy REST Web Services JSP Configuration Procedure

To configure the Oracle ATG Web 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 ATG Web Commerce applications in the ATG 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 282).

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

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

281).

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

Commerce platform. See comprehensive information about that feature in the ATG 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.

<ATG10dir>/home/servers/servername/localconfig/atg/rest/processor/templates/MyTemplate.properties

An example URL template component properties file is shown below.

• The urlTemplateFormat property defines the application path of the URL that Legacy REST Web Services

clients will access. It includes a comma separated list of parameters that the client must supply.

The URL format must begin with /rest/service. After that, it must contain the Nucleus path of an existing

component in your application. It does not matter which component you choose.

• The indirectRegex property matches parameters that are supplied in the URL application path. The URL

recoding feature will pass these parameters to the JSP.

• The regexElementList property provides information about each parameter. The two parameters shown in

this example are a repository item identifier and a simple string.

• The forwardUrlTemplateFormat property configures the JSP file that the Legacy REST Web Services

interface will invoke. The application path includes the context root of the Web application (mymodule in the

example). It also includes each parameter that was identified in the URL template as URL parameters that will

be passed to the JSP.

$class=atg.repository.seo.IndirectUrlTemplate

# Url template formaturlTemplateFormat=/rest/service/atg/AnyComponent/{item.id},{mystring}

# Regex that matches above formatindirectRegex=.*/rest/service/atg/AnyComponent/([^/].*?),([^/].*?)$

# Regex elementsregexElementList=item | id | /atg/AnyComponent\:product, mystring | string

# Forward Url templateforwardUrlTemplateFormat=/mymodule/WEB-INF/rest/myRestJsp.jsp?productId\={item.id}&myString\={mystring}

# Web App registrywebAppRegistry=/atg/registry/WebApplicationRegistry

Note: See comprehensive information about configuring the URL recoding feature of the Oracle ATG Web

Commerce platform in the ATG 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.

<ATG10dir>/home/servers/servername/localconfig/atg/rest/processor/


ServiceProcessor.properties

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 Oracle ATG Web Commerce application in the ATG

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>


Working with Repositories in Legacy REST

This section provides instructions for Legacy REST Web Services operations involving repositories.

A repository item is a JavaBean component that implements atg.repository.RepositoryItem or one of its

sub-interfaces, and corresponds to the smallest uniquely identifiable entity in the underlying data store. Each

repository item is composed of named properties that store the item’s data—for example, id, firstName, and

lastName.

Listing Repository Items in Legacy REST

To list the items of a type in a repository, send a Legacy REST Web Services request as described in the following

table.


HTTP Method GET


URL Include the component pathname of the repository in the application path after

/rest/repository/. Include the name of the item type at the end of the path.

The following example shows a Legacy REST Web Services request that lists the repository items of the user

item type in the atg/userprofiling/ProfileAdapterRepository repository.

curl -v -b cookies.txt -X GET \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4;DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 29 Oct 2010 16:27:49 GMT<<?xml version="1.0" encoding="UTF-8"?>


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


HTTP Method GET



/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


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>


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


HTTP Method GET



/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


> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4;DYN_USER_CONFIRM=2a952017db56aab256c7e7077bf1feec>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="A8D99275B90B200E0913A8831E77A9F4" fordomain myserver, path /, expire 0< Set-Cookie: JSESSIONID=A8D99275B90B200E0913A8831E77A9F4; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 29 Oct 2010 19:42:35 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <lastPurchaseDate>2010-10-27</lastPurchaseDate></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Performing RQL Queries in Legacy REST

To perform a Repository Query Language (RQL) query, send a Legacy REST Web Services request as described in

the following table. See information about repository queries in ATG Repository Guide.


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


* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> GET /rest/repository/atg/commerce/catalog/ProductCatalog/product?atg-rest-rql=ALL+RANGE+%2B4 HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=0D62D5F5145D6A1E7A2EDBC669F3BA0F;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Fri, 29 Oct 2010 21:33:00 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <product> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod2022</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod1064</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod2024</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ ProductCatalog/product/xprod1066</element> </product></atgResponse>* Connection #0 to host myserver left intact* Closing connection #0

Note: You can include the atg-rest-rql functional parameter in the message body of a POST HTTP request

if you prefer not to URL encode your RQL queries. Use the atg-rest-view control parameter to instruct the

Legacy REST Web Services server to handle your POST request as a GET request. See Handling POST Requests as

Other Methods (page 252).

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


HTTP Method POST



Functional Parameters Include all required property values for the new repository item as functional

parameters with the Legacy REST Web Services request.


/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>[email protected]</email><password>mypassword</password></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> POST /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=F9C672B8E52D2033A1B70C4EE225577F;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b> Content-Type: application/xml> Content-Length: 168>< HTTP/1.1 201 Created< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 01 Nov 2010 17:35:29 GMT<<?xml version="1.0" encoding="UTF-8"?>

<atgResponse> <repositoryId>130030</repositoryId> <securityStatus>4</securityStatus>


<lastPurchaseDate/> <lastName>Briere</lastName> <gender>unknown</gender> <salePriceList/> <categoryLastBrowsed/>



<registrationDate>2010-11-01 13:35:28.742</registrationDate> <dateOfBirth/> <member>false</member> <firstName>Roland</firstName> <billingAddress/>


<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>[email protected]</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.


HTTP Method PUT

Functional Parameters Include the new values for each property you are updating as functional



/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>[email protected]</email></parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/


ProfileAdapterRepository/user/130034

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> PUT /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130034 HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=B6D3509A03881D9CE1A1370434AD18CB;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b> Content-Type: application/xml> Content-Length: 90>< HTTP/1.1 200 OK< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1* Replaced cookie JSESSIONID="6A9888BA9F4035AF606AE7E40A435451" for domainmyserver, path /, expire 0< Set-Cookie: JSESSIONID=6A9888BA9F4035AF606AE7E40A435451; Path=/< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 01 Nov 2010 19:40:41 GMT<<?xml version="1.0" encoding="UTF-8"?>


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.


HTTP Method DELETE

Functional Parameters Include the new values for each property you are updating as functional



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


curl -v -b cookies.txt -X DELETE \http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130037

* About to connect() to myserver port 8080 (#0)* Trying 12.34.567.890... connected* Connected to myserver (12.34.567.890) port 8080 (#0)> DELETE /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130037HTTP/1.1> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5> Host: myserver:8080> Accept: */*> Cookie: DYN_USER_ID=140003; JSESSIONID=E8FF855FEF5C59ECF6FA9D1A69F1C30D;DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b>< HTTP/1.1 410 Gone< Server: Apache-Coyote/1.1< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=< Content-Type: application/xml;charset=UTF-8< Transfer-Encoding: chunked< Date: Mon, 01 Nov 2010 20:21:19 GMT<<?xml version="1.0" encoding="UTF-8"?>


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 ATG Web Commerce platform server’s configuration path. To customize it, create that file in your own

module and the server’s XML combination functionality will combine all the filteringConfiguration.xml

files.


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


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


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

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

The following filteringConfiguration.xml file defines a filtering template.

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


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

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


], ...}

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 300) and /atg/rest/output/XMLOutputCustomizer (page 301).

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


1. Add a component element to the /atg/rest/filtering/filteringConfiguration.xml configuration

file for your Oracle ATG Web Commerce platform server. Specify the Nucleus path for the virtual component

in the name attribute of that element.

2. Include one or more property elements in the component element. Either draw the value of the component

from another component property using the component and target attributes or from a custom class using

the property-customizer attribute.

The following example configuration creates a virtual component. It specifies the name of a component that

does not exist in the name attribute of the component tag, thus creating a virtual component. When creating

virtual components in this way, do not use the item-descriptor element.

When a REST client requests this component, the list of properties that are specified inside the component

element will be rendered.

<rest-filtering> <component name="/some/nonexisting/Component"> <property name="property1" component="/some/other/Component" target="aProperty"/> <property name="property2" property-customizer="some.class.Here"/> </component><rest-filtering>

Suppressing Property Expansion in Legacy REST

You can configure the Legacy REST Web Services interface to return only the string representation of specific

properties. This can be useful when you need to set the return depth to a level that returns certain deeply-

nested properties but you do not want extensive, unnecessary detail for other properties. See Return

Depth (page 268). 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:


• Suppressing Property Expansion for Java Classes (page 298)

• Suppressing Property Expansion for Specific Properties (page 298)

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

291).

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.


/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 260). 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 263). 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.


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

The following example specifies that the form handler

properties should be included in the HTTP response to a

Web Services request.

returnFormHandlerPropertiesByDefault=true


/atg/rest/output/JSONOutputCustomizer

This section explains configuration properties that are set on the /atg/rest/output/

JSONOutputCustomizer component for Legacy REST Web Services.


enableFormatDateOutput This configuration property specifies whether the Legacy

REST Web Services server will return date properties in the

following format:


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

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

This property affects requests that will return results

formatted with JSON markup. See Choosing Output

Markup (page 260).

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


parameters that affect Nucleus components when they are

presented with REST requests. See Property Filtering with




Markup (page 260).



them.



enablePerRequestRepositoryFilters This configuration property controls whether the Legacy


parameters that affect repositories when they are presented

with REST requests. See Property Filtering with Legacy

REST (page 291).



Markup (page 260).



them.

enablePerRequestClassFilters This configuration property controls whether the Legacy


parameters that affect components that subclass or

implement specific Java classes when they are presented


REST (page 291).



Markup (page 260).



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

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



enableFormatDateOutput This configuration property specifies whether the Legacy

REST Web Services server will return date properties in the

following format:


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

enablePerRequestFilters This configuration property controls whether the Legacy


parameters that are presented with REST requests. See

Property Filtering with Legacy REST (page 291).


formatted with XML markup. See Choosing Output

Markup (page 260).



them.

enablePerRequestComponentFilters This configuration property controls whether the Legacy


parameters that affect Nucleus components when they are

presented with REST requests. See Property Filtering with




Markup (page 260).



them.

enablePerRequestRepositoryFilters This configuration property controls whether the Legacy


parameters that affect repositories when they are presented


REST (page 291).



Markup (page 260).



them.



enablePerRequestClassFilters This configuration property controls whether the Legacy


parameters that affect components that subclass or

implement specific Java classes when they are presented


REST (page 291).



Markup (page 260).



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

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.


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



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 Multiple Values in Input (page 258).

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.


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

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 ATG Web Commerce platform in general.

Legacy REST Security Overview

The Legacy REST Web Services server uses the underlying security system of the Oracle ATG Web 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 ATG Web Commerce platform user interface and interacting with its

functionality.


To understand the security system used by the Legacy REST Web Services server you must understand the

system used by the Oracle ATG Web Commerce platform. See Managing Access Control in the ATG 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 253).

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 ATG Web Commerce security system and therefore uses ACLs

which are similar to those used to configure security in other parts of an Oracle ATG Web Commerce 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 ATG Web Commerce repository security is handled by the Oracle ATG Web Commerce secured repository

system, which works in conjunction with the Oracle ATG Web Commerce Security System to provide fine-

grained access control to repository item descriptors, individual repository items, and even individual properties.

For more information, see the ATG 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 ATG Web Commerce system.


<rest-security> <default-acl value="Profile$login$#username#:read,write,execute"/></rest-security>

Global Security with Legacy REST

To configure global security, use the default-acl tag. This tag defines which personas have access to Nucleus

components. In the following example, all users who are assigned the restUser role have read and write

access to all Nucleus properties and execute access for all methods on Nucleus components. The default-

acl tag is optional. This example assumes that a role called restUser has already been created in the profile

repository.

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

Component Security in Legacy REST

To configure security on a specific component, use the resource tag. This tag, along with the component

attribute, allows you to define which users have access to the specified component. You could disable security

entirely for the specified component by using the optional secure attribute.

In the following example, the /some/Component component is configured so that only the user whose login

is restAdmin has full access to it; users with the restUser role only have read access. In addition, the /some/

other/Component component is configured to disable security.

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

<resource component="/some/Component"> <default-acl value="Profile$login$restAdmin:read,write,execute; Profile$role$restUser:read"/> </resource>

<resource component="/some/other/Component" secure="false"/></resource></rest-security>

Property and Method Security in Legacy REST

To configure security on a component property or method, add a property or method tag within the resource

tag. The property and method tags allow you to control which users have access to specific properties and

methods.

By default, properties and methods of unsecured components are secured. You must explicitly list any

properties or methods that you want to expose. In the following example, the property named Property1

would default to being a secure property, however, we want that property to be accessible only to the

restAdmin, so it must be identified specifically. The property named Property2 is available to everyone since


it does not specify an ACL value. However, all other properties and methods of this component are secure by

default. Note that this does not affect what is returned by the URL, only which URLs are accessible.

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

<method name="methodB" secure="false"/> </resource>

<resource component="/some/other/Component" secure="false"/></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 279). 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 ATG Web Commerce 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 ATG Repository Guide

Securing Groups of Components in Legacy REST

The Legacy REST Web Services provide the ability to secure groups of components within the same Nucleus sub-

tree. This is accomplished by using the * wildcard character. Note that * is the only wildcard character allowed.

The following example sets the ACL for all components within the /atg/commerce sub tree to be accessible

only by users with the restCommerceUser role.

<rest-security> <default-acl>Profile$role$restUser:read,write,execute"</default-acl>


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

8 Legacy Rest Client Libraries 309

8 Legacy Rest Client Libraries

The Legacy REST Web Services package includes two client libraries:

• Java Client Library for Legacy REST (page 309)

• ActionScript Client Library for Legacy REST (page 323)

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

310 8 Legacy Rest Client Libraries

• public static RestResult getComponent(String pComponentPath, Map<String,Object>

pParams, RestSession pSession)

Returns all the properties of the specified Nucleus component.

• public static RestResult getPropertyValue(String pComponentPath, String pProperty,

Map<String,Object> pParams, RestSession pSession)

Returns the requested property from the specified Nucleus component.

• public static RestResult setPropertyValue(String pComponentPath, String pProperty,

Object pValue, Map<String,Object> pParams, RestSession pSession)

Sets a value on the specified Nucleus component property.

• public static RestResult executeMethod(String pComponentPath, String pMethodName,

Object[] pArguments, Map<String,Object> pParams, RestSession pSession)

Calls a public method on the specified Nucleus component.

The Object[] pArguments parameter is an array of method arguments. This parameter should

contain one Object for each of the method parameters. For example, if the method takes an int, then a

java.lang.Integer object should be passed. The Java client library handles converting the object for

transport to the server and the Legacy REST module handles converting it to an int. If any parameter object

is passed as a String, the parameter will be transported to the server without any changes. This means that

a method that takes an int can have a java.lang.String object with a value of 2, for example, passed. For

parameters that are complex objects, the object can be passed as a parameter and the library will attempt

to convert it for transport. When the request is sent to the server, a new instance will be constructed and its

properties populated with the values from the original object. Collections and Maps can also be transported.

For more information, see Calling Methods with the Java Client Library (page 318).

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

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


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

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

Web Commerce 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 253).

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:



Hostname The name of the host which the session will or is connected to. Default is

localhost.

Port The port number which the session will use. Default is 80.

Username The username the session will use to connect.

Password The password the session will use to connect.

Scheme The scheme the session will use to connect. Default is HTTP expect for login

calls.

restContextRoot The web application context root for Legacy REST Web Services. Default is /

rest.

useInternalProfileForLoginTells the session object to login as an internal user instead of a profile user. You

will probably need to change this property after the RestSession object is

created and before login is called. When connecting to a server that can be

accessed only by internal users, this property must be set to true or the login

will fail.

useHttpsForLogin Tells the session object to use the HTTPS scheme for login calls. Default is true.

httpsPort The HTTPS port number which the session will use. Default is 443.

userId The userId of the connected user. This value is set after logging in.

sessionId The session ID of the current session. This value is set after logging in.

Encoding The encoding to use when encoding parameter values. Default is UTF

inputFormat The default input format that is set on the server. Changing this value has no

effect on the server.

outputFormat The default output format that is set on the server. Changing this value has no

effect on the server

Starting a REST Session

When you start a REST session, the Legacy REST interface sets the session confirmation number, session id, and

the default input and output customizers.

Start a session by doing one of the following:

• Log in to the Legacy REST interface. See Logging in and Logging Out with the Java Client Library (page 313).

• Invoke the RestSession.startSession() method. This will start the session but does not authenticate the

client for access to secured Oracle ATG Web Commerce components. See Starting a Session Without Logging

In (page 314).


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

The sample first creates a RestSession object. It does this by calling the static

RestSession.createSession() method. The parameters to createSession are the hostname, port,

username, and password. By default all login calls are issued with HTTPS. If you do not want this functionality,

set the value of the useHttpsForLogin flag to false on the session object, as the following sample does. The

next section of code calls the login() method on the RestSession object. If the login attempt fails, then

a RestClientException is thrown. The last section of code calls the logout() method and concludes the

session.

import atg.rest.client.RestClientException; import atg.rest.client.RestComponentHelper; import atg.rest.client.RestResult; import atg.rest.client.RestSession;

import java.io.IOException;

public class RestClientSample {private String mUsername = null;private String mPassword = null;private String mHost = "localhost";private int mPort = 80;private RestSession mSession = null;

public RestClientSample() {}

protected void parseArguments(String[] pArgs) throws Exception { for (int i = 0; i < pArgs.length; i++) { String arg = pArgs[i];

if (arg.equals("-user")) mUsername = pArgs[i+1]; else if (arg.equals("-password")) mPassword = pArgs[i+1]; else if (arg.equals("-host")) mHost = pArgs[i+1]; else if (arg.equals("-port")) mPort = Integer.parseInt(pArgs[i+1]); }

if (isBlank(mUsername)) throw new Exception("Must supply username"); if (isBlank(mPassword)) throw new Exception("Must supply password");}

protected boolean isBlank(String pStr) { return (pStr == null || pStr.length() == 0 || pStr.trim().length() == 0);}

protected void println(String s) { System.out.println(s);


}

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.


Note: Starting a session without logging in will not give your REST client access to secured Oracle ATG Web

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


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)

http://www.dom4j.org


The following table describes the arguments for each version of this method.


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.


Other useful methods on the RestResult object are getResponseCode() and getResponseMessage().

These return the response’s response code and message, respectively. For more information, see HTTP Status

Codes (page 59).

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


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)


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)


The getItems() method retrieves multiple repository items of the same type in a single call. The following

code sample returns an array of URLs:

RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog", "product", params, session)

When a getItems() call returns many items, you can control the number of items returned with the atg-

rest-index and atg-rest-count parameters. The atg-rest-index parameter tells the server which item to

return first. The atg-rest-count parameter tells the server how many items past the index item to return.

In the following code sample, the first query, with an index of 0 and a count of 10, retrieves 10 items at a time.

The next query has an index of 10 and a count of 10, third, index of 20 and count of 10, and so on.

Map<String,String> params = new HashMap<String,String>();params.put(RestConstants.COUNT, 10);params.put(RestConstants.INDEX, 0);RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog", "product", params, session);

params.put(RestConstants.INDEX, 10);

result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog","product", params, session);

params.put(RestConstants.INDEX, 20);

result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog","product", params, session);

Repository IDs

Each repository item has a unique identifier, called a repository ID. Depending on the repository’s configuration,

the repository ID might not be exposed as a property of the repository item. However, when a repository item

is returned with a REST RepositoryHelper method, you can reliably retrieve its repositoryID by getting the

value of the repositoryId property.

Adding Repository Items

Create a repository item by calling the RestRepositoryHelper.createItem() method. You can supply a

repository ID for the newly created item or you can allow the server to generate a repository ID for you.

A createItem() call returns a data stream that contains all the properties of the created item. This is the same

data stream that is returned when you call RestRepositoryHelper.getItem().

The following code sample adds a repository item and allows the server to generate the repository ID:

RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/ProductCatalog", "product", params, session);

The following code sample adds a repository item and specifies the value of myProductId-12345 as the

repository ID:

RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/


ProductCatalog", "product", "myProductId-12345", params, session);

Deleting Repository Items

Remove a repository item by calling the RestRepositoryHelper.removeItem() method. A removeItem()

call returns a data stream that contains the string true if the item was removed. If the item was not removed,

the call throws an exception.

The following sample removes a repository item:

RestResult result = RestRepositoryHelper.removeItem("/atg/commerce/catalog/ProductCatalog", "product", "myProductId-12345", params, session);

Getting Repository Item Properties with the Java Client

The getPropertyValue() method of the RestRepositoryHelper class returns a data stream that contains

the value of the specified property.

The following sample gets the property value displayName from the product repository item.

RestResult result = RestRepositoryHelper.getPropertyValue("/atg/commerce/catalog/ProductCatalog", "product", "prod12345", "displayName", params, session);

Setting Repository Item Properties with the Java Client

The setPropertyValue() method of the RestRepositoryHelper class sets the value of the specified

property.

The following sample sets the property displayName to the string My Modified Display Name.

RestResult result = RestRepositoryHelper.setPropertyValue("/atg/commerce/catalog/ProductCatalog", "product", "prod12345", "displayName","My Modified Display Name", params, session);

Performing Queries for Repository Items

Performing queries for repository items using RQL is similar to retrieving them with getItems(),

but querying provides for more control over the items included in the results. Use the

RestRepositoryHelper.executeRQLQuery() method to execute and RQL query.

To request a range of items, use the atg-rest-index and atg-rest-count parameters with the

executeRQLQuery() method, just as you’d use them with getItems(). See Retrieving a Repository Item in

Legacy REST (page 284) for more information.

In the following example, the INDEX and COUNT keywords in the RQL language are used instead of the “atg-rest-

index” and “atg-rest-count” parameters.

Map<String,String> params = new HashMap<String,String>();params.put(RestConstants.COUNT, 10);params.put(RestConstants.INDEX, 0);RestResult result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);


params.put(RestConstants.INDEX, 10);result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);

params.put(RestConstants.INDEX, 20);result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalog", "product", "age >= 30", params, session);

Using the Java Client in Android Applications

The Java REST client includes the class AndroidIntrospectorService which implements

atg.rest.client.beans.IntrospectorService. This class is a replacement for the

java.beans.Introspector class, which does not work on Android devices.

To use the Java REST client in an Android application, include the following file in the application’s Java class

path.

META-INF/services/atg.rest.client.beans.IntrospectorService

Include the following content in the file:

atg.rest.client.beans.AndroidIntrospectorService

ActionScript Client Library for Legacy REST

ActionScript is the programming language for the Adobe Flash Player run-time environment. This library is

useful for client applications written in Adobe Flash or Adobe Flex.

Note: Legacy REST Web Services were tested with ActionScript 3.

The ActionScript client library is nearly identical in structure to the Java client library. The main difference

between the two libraries is the way they handle results:

• The Java client library uses the RestResult class to handle results.

• The ActionScript library does not include a RestResult class; instead, it handles results using a callback

mechanism. Therefore, helper class methods and the createHttpRequest() method for the ActionScript

client library take a result handler and fault/error handler functions as arguments.

The following code sample illustrates how the ActionScript client library handles results.

public function getPropertyValue():void {RestComponentHelper.getPropertyValue("/atg/dynamo/Configuration", "httpPort",null, session, handleResult, handleFault);// get the httpPort property from the Configuration component}


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

public static function getComponent(pComponentPath:String, pParams:Array,pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function getPropertyValue(pComponentPath:String, pProperty:String,pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function setPropertyValue(pComponentPath:String, pProperty:String,pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function executeMethod(pComponentPath:String, pMethodName:String,pArguments:Array, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void

atg.rest.client.RestRepositoryHelper

The RestRepositoryHelper class simplifies repository requests.

The RestRepositoryHelper class methods are written in ActionScript as follows. For details about individual

class methods, refer to the Java Client Library for Legacy REST (page 309) section.

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


public static function setPropertyValue(pRepositoryPath:String,pItemDescriptorName:String, pItemId:String, pProperty:String, pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function,pFaultHandler:Function):voidpublic static function createItem(pRepositoryPath:String,pItemDescriptorName:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function createItemWithId(pRepositoryPath:String,pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):voidpublic static function removeItem(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler: Function):void

Calling Methods with ActionScript

The ActionScript client library’s RestClientHelper class includes the following helper methods, which convert

arrays, Lists, and Objects to Multivalue objects:

public static function convertArrayToMultivalue(pValue:Array, pMultiValueType:String, pComponentType:String, pFormat:String, pSession:RestSession):Stringpublic static function convertIListToMultivalue(pValue:IList, pMultiValueType:String, pComponentType:String, pFormat:String, pSession:RestSession):Stringpublic static function convertObjectToMultivalue(pValue:Object, pMultiValueType:String, pKeyType:String, pValueType:String, pFormat:String, pSession:RestSession):String

The following table describes the arguments for each of these methods.


pMultiValueType The absolute path of a Java class, such as java.util.ArrayList. Be sure to specify

a valid class name and not an interface name.

pComponentType The class type of the component to instantiate for each element in the multivalve

type. For example, an array of integers in ActionScript could be converted to an

ArrayList of java.lang.Integer objects.

pFormat The server’s input format type. This can be retrieved from the session object’s

inputFormat property.

pKeyType

pValueType

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

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

These arguments are similar to pComponentType and are absolute names of Java

classes to use for the key and value objects in the Java Map.

Similar to the Java client library, passing arguments to methods is generally straightforward. For primitive types,

just add them to the pArguments array.


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


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

http://code.google.com/p/as3corelib/


Index 329

Index

Aactor-chains, 79

registering, 77

actors, 79

execution order, 102

passing params, 91

types, 80

Apache Axis, 35

ATGWS.dll, 45

installing, 46

CcURL, 60

command components, 62

DdynSessConf, 78, 88, 95

EEndeca Search, 152, 231

Ffilters

bean classes, in REST MVC, 108

defining in REST MVC, 109

Legacy REST, 291

modifying in REST MVC, 116

repository items, in REST MVC, 108

HHTTP

requests, 59, 63

requests in Legacy REST, 251, 260

status codes, 59, 270

JJAX-RPC, 4, 9, 11

and WSDL, 8

JMS Messages, 16

Patch Bay, 16

type, 16

JSON

output in Legacy REST, 260

output in REST MVC, 100

output, REST, 60

Mmessage sink, 18

methods

executing with Legacy REST, 251

executing with REST MVC, 84

overloaded, specifying in REST MVC, 88

ModelMap, 79, 81

and filtering, 108

and hierarchy, 84, 107

and output elements, 99

PPatch Bay, 15, 17

Rrepository

data binding Web Services, 21

delete item, 34

filtering in REST MVC, 116

items from XML, 29

items in Legacy REST, 283

match properties, 33

modify item, 32

REST, 57

cURL examples, 60

HTTP requests, 59

HTTP status codes, 59

output, 60

URLs, 58

URLs, adding parameters, 66

REST Legacy

cURL example, 61

filtering, 291

framework, 58, 249

HTTP requests, 251

HTTP status codes, 270

output, default, 260

output, JSON, 261

output, XML, 261

repositories and, 283

security, 304

URLs, 251

URLs, adding parameters, 257

REST MVC, 75

cURL example, 61

examples, external user, 121

330 Index

examples, internal users, 175

executing methods, 84

filtering bean classes, 108

filtering repository items, 108

filtering, defining, 109

framework, 58, 79

installing, 77

registering services, 77

schema, 81

security, 116

URLs, 81

URLS, error and success, 94

SScenario Actions, 16

Scenario Manager, 18

security

Legacy REST, 304

REST MVC, 116

Web Services, 12

Service Endpoint Interface (SEI), 8

mapping to WSDL, 11

servlet beans

filtering in REST MVC, 110

in Legacy REST, 282

retrieving in REST MVC, 91

session confirmation number, 78, 122, 176

disabing in Form actors, 95

disabling in Component actor, 88

SOAP, 4, 8, 9

and WSDL, 8

UURLs, 58

adding Legacy REST parameters, 257

adding REST parameters, 66

and WSDL, 9

control parameters, 63

forwarding in REST MVC, 94

Legacy REST, 251

REST MVC, 81

success and error in REST MVC, 94

WWeb Services

.Net, 44, 48

abstract data types, 5

cookies, 5, 37

DAS, 2

DCS, 2

deploying, 13

deserializer in .Net, 46, 50

deserializer in Java, 36, 42

DPS, 2

dynamic, 39, 41

exposing methods, 8

Java client, 35

JMS Messages, 15

JMS Type, 16

naming conflict, 5, 7

NucleusSecurityManager, 12

NucleusSecurityRepository, 13

primitive data types, 5, 8

Registry, 8, 11, 14

repository, for, 18

rollback a call, 35

scenario actions, 16

security, 4, 12

serializer in .Net, 46, 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

XXML

data binding, 21

data binding in REST MVC, 107

delete repository item, 34

generating schemas, 43

mapping in Web Services, 22

mapping Web Services DTD, 23

output in Legacy REST, 261

output, REST, 60

repository items, 29

schema mapping, 43

schemas, 27

validating, 32

Date post:	28-Sep-2020
Category:	Documents
Upload:	others
View:	9 times
Download:	1 times