Professional Documents
Culture Documents
Oracle ATG
One Main Street
Cambridge, MA 02142
USA
Table of Contents
1. Creating and Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Creating Custom Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
JAX-RPC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Automatic Generation of Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Session and Security Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Method Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Web Service Creation Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Anatomy of a Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Web Service Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Deploying Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Managing Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Creating JMS Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Using the JMS Message Web Service Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Structure of a JMS Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Patch Bay Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Creating Repository Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Using the Repository Web Service Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Repository Web Service Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Modifying Repository Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
RepositoryService Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Repository to XML Data Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Mapping Files and XML Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Repository Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Accessing Web Services from Java Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
About Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Before You Begin Using a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Writing a CookieContainer Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Calling Web Services from a Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Creating a Serializer and Deserializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Accessing Web Services from .NET Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
About Web Services in the Oracle Commerce Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Before You Begin Using a .NET Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Calling Web Services from a .NET Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Using the Atg.DotNet.WebService API with RepositoryItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2. Introduction to REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
REST Web Services Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
REST Web Services URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
HTTP Request Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Returning Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Using cURL for Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Writing cURL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Server Response to cURL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
cURL Command Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Adding Control Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Functional Parameters for Oracle Commerce Platform REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Using Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Using URL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Using Message Body Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
I. Oracle Commerce Platform REST MVC Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
iii
iv
127
128
128
128
129
129
129
131
131
131
132
132
133
133
134
135
135
136
137
137
140
140
141
142
143
143
145
146
146
146
147
147
148
149
149
150
150
153
154
154
155
155
156
158
159
159
159
160
160
161
161
161
162
vi
162
162
163
164
164
165
165
166
166
167
167
168
168
169
169
171
172
174
174
175
175
177
177
178
179
179
179
180
180
181
181
181
181
182
183
184
185
185
186
186
187
188
188
189
190
190
191
191
192
193
194
198
200
Viewing a Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Customer Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating an Existing Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Note to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Searching for a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Clearing a Customer Search Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Customer to Work On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Customer Profile Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding an Address to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing an Address in a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting an Address from a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Credit Cards Within a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Credit Card to a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing a Credit Card in a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Credit Card from a Customer Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Multiple Items to a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Items to a Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating the Customers Shopping Cart by SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating the Customers Shopping Cart by Commerce ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating the Customers Shopping Cart By Shipping Group Relationship ID . . . . . . . . . . . . . . . .
Removing and Adding an Item to the Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing an Item From the Customers Shopping Cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing an Item From a Customers Shopping Cart By Relationship ID . . . . . . . . . . . . . . . . . . . .
Starting the Checkout Process with SKU ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Checkout Process with Commerce ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Checkout Process with Relationship ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the SKU of an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting the Customer with the Shipping Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Available Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying a Single Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Multiple Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Splitting Items into Different Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying All Available Shipping Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating New Hardgood Shipping Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing a Hardgood Shipping Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining the Customers Current Shipping Info List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting the Customer with the Billing Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Display the Customers Payment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Available Payment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Claiming Store Credit or a Gift Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Claiming a Customers Coupon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying Multiple Payment Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Credit Cards Within an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting a Customers Existing Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Credit Card to an Existing Address in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Credit Card to a New Address in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updating a Credit Card in an Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assisting Customers with Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating New Orders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
200
201
201
203
204
204
206
206
207
208
209
209
210
210
211
213
213
216
217
218
219
219
220
220
220
221
221
221
222
222
222
223
223
224
224
225
226
226
227
228
228
229
229
231
232
232
233
233
233
234
235
236
236
vii
viii
237
237
239
241
241
242
243
244
245
247
248
248
249
249
250
250
251
251
254
255
256
256
257
258
258
259
259
260
260
260
261
262
263
263
264
264
265
265
266
266
267
267
268
269
269
270
270
270
271
271
271
272
273
274
274
274
275
275
275
276
276
276
277
278
278
279
279
281
282
283
283
283
284
284
285
286
286
288
289
289
289
290
291
291
293
294
297
297
297
298
298
298
299
299
300
300
300
301
302
302
303
303
304
304
305
305
ix
Discarding an E-Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Customer E-Mail and Closing Ticket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with the Commerce Service Center Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Global Session Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Listing Available Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Ticket Disposition Warnings and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
II. Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7. Using Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HTTP Requests for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Nucleus Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling POST Requests as Other Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging In as an External User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging In as an Internal User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functional Parameters for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Positional Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input Values in Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returned Data in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Choosing Output Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JSON Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Values in Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Date Format in Returned Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Errors and Exceptions in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Problems Performing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Problems Processing a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Legacy REST Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Legacy REST Component Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Legacy REST Component Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Legacy REST Form Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Submitting Legacy REST Form Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning Legacy REST Form Handler Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning Legacy REST Form Handler Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Legacy REST Form Value Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoking Java Server Pages (JSPs) with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Legacy REST Web Services JSP Configuration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
URL Templates for Legacy REST Web Services JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Legacy REST Service Processor Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example Legacy REST Web Services JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Repositories in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Listing Repository Items in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving a Specific Property Using Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performing RQL Queries in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
306
306
307
307
308
309
310
311
315
317
317
317
317
318
318
319
319
320
322
323
323
325
331
331
332
332
333
334
339
340
341
341
342
343
343
344
345
346
347
348
348
349
350
351
351
352
353
354
354
355
356
357
358
Transient Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Repository Item Properties in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting a Repository Item in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Property Filtering with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Filtering in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering Templates with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering for One Request with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Property Aliasing with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suppressing Property Expansion in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filtering Priority in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Legacy REST Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/processor/BeanProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/output/JSONOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/output/XMLOutputCustomizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/processor/RepositoryProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/atg/rest/processor/RestSecurityProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Security for Legacy REST Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Legacy REST Security Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Quick Setup for Testing Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Global Security with Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Component Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Property and Method Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Repository Security in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Securing Groups of Components in Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8. Legacy Rest Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a RestSession Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting a REST Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging in and Logging Out with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting a Session Without Logging In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Data from the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Raw REST Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Components with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Methods with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Repository Items with the Java Client Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Java Client in Android Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ActionScript Client Library for Legacy REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atg.rest.client.RestComponentHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atg.rest.client.RestRepositoryHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Methods with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting Input with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
360
360
361
362
362
365
366
367
368
369
369
370
370
371
372
374
375
375
375
376
377
377
377
378
378
381
381
381
383
384
385
386
387
388
389
390
390
392
395
395
396
396
397
399
401
xi
xii
A common requirement for enterprise applications is the ability to share data and business logic with other
applications. For example, suppose you have an employee portal built with the Oracle Commerce Platform,
and also a payroll system based on some other software package. When a new employee starts, or an existing
employee changes his or her marital status, you need to create or modify the employees profile in both systems.
Ideally, youd like the employee to be able to make the changes in one application and have those changes
automatically propagate to the other application.
One way to address this issue is through Web Services, a widely supported standard for packaging remote
procedure calls in an XML-based structure. In the example above, you could create a Web Service that
automatically updates an employees profile in the employee portal when the information in the payroll system
is modified.
The Dynamo Application Framework includes tools that allow you to create custom Web Services that call
methods on Nucleus components. These custom Web Services can expose methods on existing Oracle
Commerce Platform Nucleus components, or on Nucleus components you write yourself. You can call these Web
Services from an external application client, such as the payroll system mentioned above.
The Oracle Commerce Platform packages Web Services as: J2EE applications, in accordance with the JAX-RPC
(JSR 101) and Implementing Enterprise Web Services (JSR 109) specifications. Note that this manual assumes
that youre familiar with these specifications, and with Web Services in general. For more information about
these specifications, see the Java Community Process Web site at:
http://www.jcp.org
The following sections discuss how to create Web Services in the Oracle Commerce Platform, and how to write
Java and .NET clients that call these services:
Creating Custom Web Services (page 4)
Creating JMS Web Services (page 15)
Creating Repository Web Services (page 18)
Repository to XML Data Binding (page 21)
Accessing Web Services from Java Clients (page 35)
Accessing Web Services from .NET Clients (page 44)
Web Services
In addition to any Web Services you create, the Oracle Commerce Platform includes a number of prepackaged
Web Services that you can call from Java and .NET clients. These services are packaged in three separate
application modules. You can include any of these services in an assembled EAR file by including the module
that contains the desired services. For example, to include the prepackaged Oracle Commerce Core Commerce
Web Services, specify the DCS.WebServices module when you assemble your application.
The following table summarizes these Web Services.
Note: The following services are available in DAS.WebServices. For more information about these Web
Services, see the Repository Guide.
Web Application
Web Services
getRepositoryItem
performRQLQuery
performRQLCountQuery
The following services are available in DPS.WebServices. For more information about these Web Services, see
the Personalization Programming Guide.
Web Application
Web Services
User Session
loginUser
logoutUser
getProfileId
setLocale
setContactInfo
setPassword
getProfile
createUser
updateUser
getPasswordHashKey
getPasswordHashAlgorithm
canClientEncryptPasswords
executeRepositoryTargeter
Messaging
sendPageVisit
sendClickThrough
The following services are available in DCS.WebServices. For more information about these Web Services, see
Core Commerce Programming Guide.
Web Application
Web Services
Order
createOrderFromXML
submitOrderWithReprice
cancelOrder
getOrderStatus
getOrderAsXML
getOrdersAsXML
getOrderStatus
getCurrentOrderId
addItemToOrder
addItemToShippingGroup
createOrder
createOrderForUser
removeItemFromOrder
setItemQuantity
addCreditCardToOrder
addShippingAddressOrder
removePaymentGroupFromOrder
removeCreditCardFromOrder
removeShippingGroupFromOrder
moveItemBetweenShippingGroups
removeItemQuantityFromShippingGroup
setOrderAmountToPaymenGroup
getDefaultPaymentGroupId
getDefaultShippingGroupId
Pricing
calculateOrderPrice
calculateOrderPriceSummary
calculateItemPriceSummary
Promotions
grantPromotion
revokePromotion
claimCoupon
getPromotionsAsXML
Inventory
getInventory
getInventoryStatus
setStockLevel
setStockLevels
Catalog
getProductXMLById
getProductXMLByDescription
getProductXMLByRQL
getProductSkusXML
catalogItemViewed
Profile
setDefaultShippingAddress
setDefaultBillingAddress
setDefaultCreditCard
getDefaultShippingAddress
getDefaultBillingAddress
getDefaultCreditCard
JAX-RPC Support
The Web Services support in the Oracle Commerce Platform is based on JAX-RPC (Java API for XML-based RPC).
The JAX-RPC specification defines a standard way for incoming XML-based SOAP messages to be converted to
Java-based RPC calls. The Oracle Commerce Platform uses Oracles reference implementation of JAX-RPC. Parts
of this reference implementation are used to generate Web Services, and other parts of it handle the processing
of SOAP messages when a Web Service is called.
To enable multiple Web Services to execute within the same session, a client application must pass a session
cookie between calls. Some Web Services frameworks, such as Microsofts .NET, provide support for passing
session cookies. Java clients typically require applications to manage session cookies themselves.
For more information about using sessions with Java clients, see the Accessing Web Services from Java
Clients (page 35) section. For more information about using sessions with .NET clients, see the Accessing Web
Services from .NET Clients (page 44) section.
Method Limitations
You can create Web Services from most Nucleus methods, both from components Oracle Commerce Platform
provides and components that you write. There are, however, some methods that cannot be exposed as valid
Web Services. The Web Service Creation Wizard does not create Web Services from these methods. In particular,
it enforces the following restrictions by preventing you from selecting these methods:
You cannot create a Web Service from any method that has a parameter or return type that is an abstract data
type (such as a Map, Collection, Interface, abstract class, or an object with abstract data type properties)
You cannot create a Web Service from any method that has a parameter or return type that is a wrapper class
for a primitive data type. The prohibited classes are Byte, Boolean, Character, Integer, Short, Long,
Float, and Double. Note, however, that methods that use actual primitives are valid. If there is a method that
you want to expose that has one of these wrapper classes as a parameter or return type, you can either rewrite
the method to use a primitive instead (if the methods class is your own custom code), or else subclass the
methods class (if it is a class provided by Oracle Commerce Platform) and overload the method with a version
that uses primitives
In addition, you cannot create a Web Service from a method that has the same name and signature as any of
the methods of atg.webservice.ManagedComponentProperties or java.lang.Object. Attempting to
do so results in a naming conflict, because the service implementation class of each Web Service subclasses
atg.webservice.ManagedComponentProperties, which subclasses java.lang.Object. Note that the
wizard does not prevent you from selecting these methods, but when you try to generate a Web Service, an
exception is thrown and the service generation fails.
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.
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.
WSDL Document
Web Services Description Language (WSDL) is an XML language for describing Web Services in a platformindependent way. A WSDL document describes a Web Services methods by specifying the locations of the
resources they use and defining the methods inputs and outputs. (A WSDL document for a Web Service
generated by the Oracle Commerce Platform always describes one method, because each Web Service can
expose only one Nucleus method.)
There must be a separate WSDL document for each Web Service. The WSDL document is generated by the /
atg/webservice/WSDLGenerator component, which is of class atg.webservice.WSDLGeneratorImpl.
This document is used for two key purposes:
It is used by the JAX-RPC API to generate runtime classes
At runtime, it is used by Web Service clients to look up the semantics of the SOAP messages to send to invoke
the service
When the Web Services input and output values are primitive types, they are defined in the primary WSDL
document. For example:
<message name="getOrderStatusInput">
Each non-primitive input or output requires its own WSDL document that is imported by the primary WSDL
document. Import statements similar to the following are included in the primary WSDL document when the
Web Service is created using the Dynamo Administration UI:
<import location="atg.commerce.order.status.wsdl"
namespace="http://www.atg.com/atg.commerce.order.status"/>
The location specified is relative to the primary WSDL document. Some Web Service clients are
able to interpret relative locations, but others require fully qualified URLs. To work with these clients,
when the Oracle Commerce Platform receives a request for a WSDL document, it uses the servlet class
atg.webservice.WSDLFinderServlet and the filter class atg.webservice.WSDLImportFilter to
translate the location value into a fully qualified URL:
1. At runtime, JAXRPCServlet updates the SOAP address in the WSDL document to include the domain host
name and port number.
2. When WSDLFinderServlet detects a WSDL request, WSDLImportFilter appends the domain name
and port number (from the SOAP address provided by JAXRPCServlet) and the context path (by calling
request.getContextPath() on the Dynamo request) to the location value in the import statement.
The resulting import statement looks similar to this:
<import location=
"http://myhost:7881/catalog/atg.commerce.order.status.wsdl"
namespace="http://www.atg.com/atg.commerce.order.status"/>
The WSDLFinderServlet and WSDLImportFilter classes are declared in the web.xml file for the Web
application that the Web Service is a part of, as discussed in the next section. For more information about
request handling, see the Platform Programming Guide.
web.xml File
The web.xml file is the standard deployment descriptor for the Web application that the Web Service is a part of.
It declares the filters and servlets used by the service.
With Oracle Commerce Platform, the servlet that listens for the SOAP request is
com.sun.xml.rpc.server.http.JAXRPCServlet. This servlet is part of the JAX-RPC reference
implementation, and is responsible for receiving the incoming SOAP request and determining how to dispatch
the call. For example, if you create a Web Service called getOrderStatus, the entry for it in the web.xml file
looks something like this:
<servlet>
<servlet-name>getOrderStatus</servlet-name>
<display-name>getOrderStatus</display-name>
<servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet</servlet-class>
<init-param>
<param-name>configuration.file</param-name>
<param-value>WEB-INF/wsconfig/getOrderStatus_Config.properties</param-value>
</init-param>
</servlet>
...
<servlet-mapping>
<servlet-name>getOrderStatus</servlet-name>
<url-pattern>/getOrderStatus/*</url-pattern>
</servlet-mapping>
When a call to the getOrderStatus Web Service is sent to the Oracle Commerce Platform, the JAXRPCServlet
receives the request and dispatches it based on the information in the file that the configuration.file
parameter points to. This configuration file is included in the WAR file, and looks similar to this:
port0.wsdl.serviceName=GetOrderStatusSEIService
port0.tie=webservices.GetOrderStatusSEI_Tie
wsdl.transform=true
port0.name=getOrderStatus
portcount=1
wsdl.location=WEB-INF/getOrderStatus.wsdl
port0.servant=webservices.GetOrderStatusSEIImpl
port0.wsdl.targetNamespace=http\://www.atg.com/webservices
port0.wsdl.portName=GetOrderStatusSEIPort
Note that the port0.servant property is set to the name of the service implementation class. This property
designates the class that JAXRPCServlet dispatches the SOAP request to.
<filter>
<filter-name>WSDLImportFilter</filter-name>
<filter-class>atg.webservice.WSDLImportFilter</filter-class>
</filter>
...
<filter-mapping>
<filter-name>WSDLImportFilter</filter-name>
<url-pattern>/getOrderStatus/*</url-pattern>
</filter-mapping>
...
<servlet>
<servlet-name>WSDLFinder</servlet-name>
<display-name>WSDLFinder</display-name>
<description>Used to lookup imported wsdl files.</description>
<servlet-class>atg.webservice.WSDLFinderServlet</servlet-class>
</servlet>
...
<servlet-mapping>
<servlet-name>WSDLFinder</servlet-name>
<url-pattern>atg.commerce.order.status.wsdl</url-pattern>
</servlet-mapping>
10
<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>
<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).
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
11
Classes for handling serializing and deserializing SOAP requests and responses
Security Components
There are two primary components involved in securing a Web Service method:
/atg/webservice/security/NucleusSecurityManager (an instance of
atg.webservice.NucleusSecurityManager) uses the security configuration associated with the Web
Service to apply the corresponding security policy and ACL, to determine whether to grant or deny access.
See NucleusSecurityManager (page 12)
/atg/webservice/security/NucleusSecurityRepository (an instance of
atg.adapter.gsa.GSARepository) stores the Web Service security configurations used by the
NucleusSecurityManager. See NucleusSecurityRepository (page 13)
NucleusSecurityManager
At startup time, the NucleusSecurityManager retrieves the repository items from the
NucleusSecurityRepository (described below) and creates an internal mapping between each functional
name and the SecurityPolicy component and ACL associated with it.
When a client calls a Web Service, the service invokes the hasAccess() method on the /atg/webservice/
security/NucleusSecurityManager component, passing it the functional name of the services security
configuration, the name of the Nucleus component and method exposed by the service, and a Map containing
the methods parameters. The NucleusSecurityManager uses the functional name to find the associated
SecurityPolicy component and ACL, applies them to the call, and returns the result (true or false) to the
client. If true is returned, the Nucleus method exposed by the Web Service is invoked; if false is returned,
access to the method is denied, and an exception of class atg.security.SecurityException is thrown.
If the NucleusSecurityManager is unable to apply the security configuration to a Web Service call (for
example, if the SecurityPolicy is not valid), it determines whether to grant access based on the value of its
defaultGrantAccess property. The default value of this property is false (deny access).
12
Setting defaultGrantAccess to true facilitates the development process, because it allows any Web Service
that does not have an associated security configuration to be called by any client.
For deployment purposes, though, this behavior is undesirable, because of the security risks involved. Therefore,
when you enable liveconfig settings for the Oracle Commerce Platform, the defaultGrantAccess property
is set to false. Note, however, that this means that each of your Web Services must have an associated security
configuration, because any call to a service without a security configuration will fail.
For information about enabling liveconfig settings, see the Platform Installation and Configuration Guide
NucleusSecurityRepository
Web Service security configurations are stored in the NucleusSecurityRepository. This repository includes
a single item descriptor called nucleusSecurity, which has properties called functionalName, policy, and
ACL. The NucleusSecurityManager parses the items in this repository at startup time.
The Web Services Administration interface provides an easy way to add new security configurations to this
repository. See the next section for details.
13
If you make any subsequent changes to the Web Service, you must reassemble and redeploy the application for
the changes to take effect.
Note that in addition to any Web Services you create, the Oracle Commerce Platform includes a number of
prepackaged Web Services. These services are packaged in three separate application modules. You can include
any of these services in an assembled EAR file by including the module that contains the desired services. For
example, to include the prepackaged Core Commerce Web Services, specify the DCS.WebServices module
when you assemble your application.
For more information about the runAssembler command, see the Platform Programming Guide. For information
about deploying EAR files, see the documentation from your application server vendor.
The Service Info indicates that there are six Web applications running that include Web Services. You can get
more information about the services in a Web application by clicking the Details link next to the applications
name. For example, if you click on the link for the Pricing application, the Service Info looks like this:
14
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.
15
are triggered by JMS messages, so by calling a Web Service that sends a JMS message, a client can start
execution of various services and processes. In particular, scenario actions are triggered by JMS messages, so
you can use Web Service calls to invoke scenario actions remotely. For example, suppose a new user registers
in some application, which invokes a Web Service that sends the registration information to the Oracle
Commerce Platform. The client application could then call a Web Service that sends a JMS message of type
atg.dps.Register into Patch Bay, thereby triggering a scenario action that (for instance) sends an e-mail
message to the new user.
This section discusses how to create Web Services that send JMS messages, and how to configure components
to listen for these messages. For more information about JMS and Patch Bay, see the Dynamo Message System
chapter of the Platform Programming Guide.
16
The service implementation class then calls the receiveObjectMessage() method like this:
messageImporter.receiveObjectMessage(a, "atg.dps.PageVisit",
"IndividualEvents");
For information about calling Web Services that send JMS messages from Java clients, see the Accessing Web
Services from Java Clients (page 35) section. (Note that you cannot use the dynamic process described in
that section for calling these Web Services.) For information about calling Web Services that send JMS messages
from .NET clients, see the Accessing Web Services from .NET Clients (page 44) section.
<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>
17
The Scenario Manager is a message sink configured to receive messages from these destinations. This
configuration occurs in two places:
In the standard Patch Bay configuration file, the Scenario Manager is configured to receive individual scenario
events from the destination patchbay:/sqldms/MessageImporter/IndividualEvents
In the /atg/dynamo/messaging/dynamoMessagingSystemDSSGlobal.xml file, the Scenario Manager is
configured to receive global scenario events from the destination patchbay:/sqldms/MessageImporter/
CollectiveEvents
You can configure other message sinks to receive messages from the patchbay:/sqldms/MessageImporter/
IndividualEvents destination by declaring them in the dynamoMessagingSystem.xml file. Note, however,
that you cannot configure other sinks to receive messages from patchbay:/sqldms/MessageImporter/
CollectiveEvents. This destination is a queue, used by global Scenario Managers only; adding sinks to this
destination may interfere with the global Scenario Managers receiving messages. If you want another message
sink to receive these messages, configure an additional destination for MessageImporter to send global
scenario events to, and configure your sink to listen to that destination instead.
18
get
The Select Method page also allows you to create a Web Service for a specific property. The page displays a
list of links for each of the properties of the item descriptor you selected. Click one of these property names to
create a Web Service for an individual repository item property.
The property name link leads to a list of the Web Service methods that are available for that repository item
property, as well as notes about the Web Service limitations, if any, related to the repository item property.
See Repository Web Service Limitations (page 19) for more information.
Click the name of the method you want to expose in your Web Service.
5. In the EAR Name & Servlet Settings page, the Web Service Creation Wizard displays default names for the
EAR file and servlet to be created. You can modify the default names. You can also, if you choose, enter a
description for the servlet and a network hostname and port number for the Web Service. If you leave the
fields blank, the values are dynamically assigned at runtime from the URL used for the WSDL file request. You
should generally leave these fields blank, unless you want to require the Web Service to be accessed on a
specific server and port.
Enter any settings you want to change and click the Next button.
6. In the Enterprise & Web Application Settings page, the Web Service Creation Wizard displays default names
for the enterprise application and Web application to be created. You can modify the default names. You can
also, if you choose, enter a description for the enterprise application and Web application.
Enter any settings you want to change and click the Next button.
7. The Session & Security Options page allows you to select one of the following three options for the Web
Service:
Provide neither a session nor security constraints
Provide a session, but no security constraints
Provide both a session and security constraints
If you choose the last option, the wizard then prompts you to select a security configuration. See the Creating
Custom Web Services (page 4) section for information about security configurations for Web Services.
8. The Create EAR File page displays the parameter values you have selected for your Web Service. Review them,
then click the Create EAR File button to create the Web Service.
The Web Service is created in an EAR file. You will find the EAR file in the <ATG11dir>/home directory, with
the name you selected in step 4.
To use the new Web Service, you need to deploy it. See the Deploying Web Services (page 13) section.
get/setPropertyValue
Collection properties may not be set or gotten as a whole. Only elements of the collection may be set
19
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
RepositoryService Class
The atg.repository.RepositoryService class contains many methods that perform basic Repository
operations, independent of any particular repository implementation or instance. Such operations include
getting, adding, removing and updating a repository item, setting and getting properties of repository items,
and performing queries for repository items using RQL. Using the Web Service generator, you can directly make
some of these methods into Web Services by simply clicking a form submit button.
Some others of these methods are too generic to be made available as a Web Service without limiting the
types of the inputs or outputs. For example, the method setPropertyValue takes a java.lang.Object as a
20
method argument for the property value. Since Web Services does not allow java.lang.Object as an input
(or output), this method cannot be used as a Web Service in this form. However, we can restrict the type of this
argument using the code generator template functionality, so when the Web Service is generated, the outwardfacing method will be strongly typed based on the property being set, and can simply call through to the more
generic setPropertyValue method in the body of the Web Service. The RepositoryService class has the
following properties:
Property Name
Type
Description
transaction
Manager
javax.transaction.
TransactionManager
mappingManager
atg.repository.xml.
ItemDescriptor
MappingManager
xmlGetService
atg.repository.xml.
GetService
xmlAddService
atg.repository.xml.
AddService
xmlUpdateService
atg.repository.xml.
UpdateService
For information about the XML service properties, see the Repository Operations (page 29) section.
21
The data binding facility also includes tools for generating XML Schemas that describe the structure of data in a
repository, and to use these XML Schemas to validate the data written out from or read into the repository. For
information on the Integration Framework, refer to the Platform Programming Guide.
The data binding facility provides services that perform these four operations with repository items:
Getting items (retrieving items from a repository and writing them out to XML documents)
Adding items (creating new items in a repository from data in XML documents)
Updating items (modifying existing items using data in XML documents)
Removing items (deleting items as indicated in XML documents)
This section discusses:
Mapping Files and XML Schemas (page 22)
Repository Operations (page 29)
Note that the classes described in this section work only with repositories included in the
initialRepositories property of the /atg/registry/ContentRepositories component.
Mapping Files
When you exchange data between the Oracle Commerce Platform and a remote system, you will typically want
to exclude certain data. For example, the Core Commerce profile usually includes Dynamo-specific information
about scenarios.
When you create an XML instance document from data in a repository, Dynamo includes and excludes certain
properties by default:
If a property is readable and does not point to another item descriptor, it is included
If a property is readable, points to another item descriptor, and its cascade attribute is set to "delete", it is
included
All other properties are excluded
For more information about the default inclusion rules, see the isIncludeProperty() method of the
atg.repository.xml.RepositoryXMLTools class in the ATG Platform API Reference. RepositoryXMLTools
is a utilities class with various methods for encoding and decoding item descriptors, property names, and
mapping files to and from XML-compatible namespaces and identifiers.
If you want more explicit control over the properties that are written out, you can use a mapping file. A mapping
file specifies what properties to include or exclude when moving data between a repository and an XML
instance document, and provides a way to map the names of Dynamo properties to their equivalents in a
remote system. For example, a Dynamo profile might have an email property that stores the same information
as the Email_Address attribute on another system.
22
The following is the Document Type Definition (DTD) for mapping files:
<!-This is the XML DTD for ItemDescriptorMapping
-->
<!-Specifies what properties in an item-descriptor should be included in
another datamodel. A given mapping file gives the ability to
control what properties are included/excluded from the datamodel
control how names in one model relate to names in another model
-->
<!-Defines the mapping for a given item-descriptor. The name and repository
property are required properties. The name property corresponds to the
name of a given item-descriptor. The repository should be the Nucleus
path to a particular repository. For example, if an item-descriptor mapping
was going to point to the the ProfileAdapterRepository located at
/atg/userprofiling/ProfileAdapterRepository Nucleus path, then the repository
property should be the string "/atg/userprofiling/ProfileAdapterRepository".
The default-include exists to indicate whether or not properties that are
associated with this item-descriptor should be included by default or not.
This property defaults to true. So, if a property is does not explicitly
appear as a child property element, it is assumed to be included in the
data model to be exported.
-->
<!ELEMENT item-descriptor (property*)>
<!ATTLIST item-descriptor
repository-path CDATA #IMPLIED
name CDATA #IMPLIED
default-include (true | false) #IMPLIED>
<!-A property element controls two aspects of including a property in a given
mapping; whether the property should be included or not and what the
targetName for the target datamodel should be. The name attribute corresponds
to the name of a property defined for a given item-descriptor. The include
attribute is optional. If it is not specified, the value is obtained from the
default-include value of the enclosing item-descriptor.
-->
<!ELEMENT property (item-descriptor*)>
<!ATTLIST property
name CDATA #REQUIRED
include (true | false) #IMPLIED
targetName CDATA #IMPLIED>
The following is a sample mapping file for the Dynamo profile repository:
<!DOCTYPE item-descriptor
SYSTEM
"http://www.atg.com/dtds/databinding/itemDescriptorMapping_1.0.dtd">
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
23
name="user"
default-include="true">
<property name="homeAddress" include="true">
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="contactInfo"
default-include="false">
</item-descriptor>
</property>
<property name="slotInstances" include="false"/>
<property name="scenarioInstances" include="false"/>
<property name="mailings" include="false"/>
<property name="scenarioValues" include="false"/>
<property name="firstName" targetName="first_name"/>
</item-descriptor>
The data binding services all work with a single item descriptor and its properties (including any other item
descriptors that are properties of the main item descriptor). The mapping file uses the item-descriptor tag to
specify the repository and item descriptor that the mapping file is associated with:
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="user"
default-include="true">
The default-include attribute specifies whether the items properties should be included or excluded by
default. This value can be overridden for individual properties. In this mapping file, various scenario-related
properties are excluded:
<property
<property
<property
<property
name="slotInstances" include="false"/>
name="scenarioInstances" include="false"/>
name="mailings" include="false"/>
name="scenarioValues" include="false"/>
If a property is an item descriptor, there must be an item-descriptor tag inside the property tag. For
example, the homeAddress property points to a contactInfo item descriptor:
<property name="homeAddress" include="true">
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="contactInfo"
default-include="false">
</item-descriptor>
</property>
Note that the item-descriptor tag for contactInfo can have property tags within it. The nesting of
property tags and item-descriptor tags must reflect the hierarchy of the item descriptors in the repository.
If you do not include a property tag for a property that points to an item descriptor (such as the homeAddress
property shown above), the Oracle Commerce Platform uses the default inclusion rules for determining which
properties of that item descriptor to include.
Finally, the property tag has an optional targetName attribute for mapping the property name to its
corresponding name in the remote system:
24
ItemDescriptorMapping
An ItemDescriptorMapping is a simple bean that holds information about relationships between repository
item descriptors and mapping files. The mapping files describe what properties are to be exposed when
an item from that item descriptor is to be transformed into XML. Each ItemDescriptorMapping pertains
to exactly one repository: for example, you would have a UserProfileItemDescriptorMapping, or a
PromotionItemDescriptorMapping component, each of which would provide a list of item descriptor names
from the corresponding repository and their corresponding mapping files.
An ItemDescriptorMapping contains only three properties:
Property Name
Type
Description
repositoryPath
java.lang.String
repository
atg.repository.
Repository
itemDescriptorMapping
java.util.Map
Here is an example properties file for an ItemDescriptorMapping that supports the profile repository:
$class=atg.repository.xml.ItemDescriptorMapping
repository=/atg/userprofiling/ProfileAdapterRepository
itemDescriptorMapping=\
user=/atg/userprofiling/userMapping.xml,\
contactInfo=/atg/userprofiling/contactInfoMapping.xml
25
Here we see the there are two entries in the itemDescriptorMapping property, one for the user item
descriptor, and one for the contactInfo item descriptor.
Whenever an entry is added to the itemDescriptorMapping property, whether through a properties file,
or directly in code, the ItemDescriptorMapping checks to make sure that the key of the entry, the item
descriptor name, resolves to an actual item descriptor of the repository this service is configured to support. If
any item descriptor name does not resolve, a RepositoryException is thrown.
By themselves, ItemDescriptorMappings perform no work. They simply hold state. In order to put them to
work, you must add them to the ItemDescriptorMappingManager, described below.
ItemDescriptorMappingManager
Class
atg.repository.xml.ItemDescriptorMappingManager
Component
/atg/repository/xml/ItemDescriptorMappingManager
Module
DAS
Property Name
Type
Description
itemDescriptorMappings
atg.repository.xml.
ItemDescriptor
Mapping[]
An array of ItemDescriptorMapping
components. When a user calls methods to
retrieve mapping files, this component sifts
through the itemDescriptorMappings to
determine the correct mapping.
$class=atg.repository.xml.ItemDescriptorMappingManager
itemDescriptorMappings=\
/atg/userprofiling/UserProfileItemMapping,\
/atg/userprofiling/ContactInfoItemMapping
Using the given repository path and item descriptor name, returns the mapping file for that given path:name
combination, or null if none exists.
getMappingFileName(Repository pRepository, String pItemDescriptorName)
Using the given repository and item descriptor name, returns the mapping file for that given repository:name
combination, or null if none exists.
26
When you use the atg.repository.xml.GetService to get repository items in XML form, you can
pass along a mapping file name using these ItemDescriptorMappingManager methods. Using the
ItemDescriptorMappingManager, you can centralize all mapping files in one component for all item
descriptors, and just call that to determine which mapping file to use for a given item descriptor.
XML Schemas
The Oracle Commerce Platform provides tools for creating and working with XML Schemas for the XML
documents written and read by the various data binding services. XML Schema is a schema language for XML
that describes and restricts what a particular XML instance document might look like. An XML document can be
validated against an XML Schema to check that it conforms to that Schema. Additionally, many developer tools
make use of XML Schemas. For example, some tools provide a visual representation of XML Schemas to allow
mapping from one XML Schema to another. See Generating XML Schemas (page 27).
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
-schemaGenerator
-m
-help
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):
27
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 .
Notice that only the name of the mapping file is specified, not the entire pathname. The Schema Managers
mappingFileDirectories property points to the directories where the mapping file should be stored.
PropertyElementNameSeparator
The repository2xml feature specifies a separator character, which functions to separate a property name
from the name of its item descriptor. By default, this separator character is . (dot). The default separator
character may not work for you if, for example, you use composite repository IDs that also use the . (dot)
character to separate elements of the repository ID. You can specify a different separator character in the
propertyElementNameSeparator property of the /atg/repository/xml/RepositoryXMLTools
component.
Item References
In a repository schema, a map, set, list, or array property can point to a single other item using the itemRef
attribute. The value assigned to the itemRef attribute concatenates the item descriptor name, the property
element separator, and the repository ID. In the following example, the item descriptor name is role, the
property element separator is . (dot) and the repository ID is 2900004:
28
<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.
29
The following is sample output from this code. The data represents the profile of the user sandy in the Quincy
Funds demo:
<user:user xmlns:user="http://www.atg.com/ns/profileMapping/UserProfiles/user"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user
profileMapping+UserProfiles+user.xsd " ID="user747">
<user:securityStatus>0</user:securityStatus>
<user:actualGoals>long-term</user:actualGoals>
<user:gender>female</user:gender>
<user:fundShares>
<user:integer>500</user:integer>
<user:integer>220</user:integer>
<user:integer>180</user:integer>
<user:integer>260</user:integer>
</user:fundShares>
<user:goals>short-term</user:goals>
<user:dateOfBirth>1976-12-09</user:dateOfBirth>
<user:pubPrivileges>none</user:pubPrivileges>
<user:homeAddress>
<user:homeAddresscontactInfo ID="contactInfo747"/>
</user:homeAddress>
<user:numberNewsItems>4</user:numberNewsItems>
<user:strategy>conservative</user:strategy>
<user:locale>en_US</user:locale>
<user:lastActivity>2002-08-14T18:33:49.604</user:lastActivity>
<user:aggressiveIndex>5</user:aggressiveIndex>
<user:lastName>Pieta</user:lastName>
<user:actualStrategy>conservative</user:actualStrategy>
<user:interests>
<user:string>tax</user:string>
<user:string>international</user:string>
</user:interests>
<user:id>747</user:id>
<user:fundList>
<user:string>/repositories/Funds/en_US/overseas.xml</user:string>
<user:string>/repositories/Funds/en_US/moneymarket.xml</user:string>
<user:string>/repositories/Funds/en_US/growth.xml</user:string>
<user:string>/repositories/Funds/en_US/growthincome.xml</user:string>
</user:fundList>
<user:email>sandy@example.com</user:email>
<user:password>d686a53fb86a6c31fa6faa1d9333267e</user:password>
<user:registrationDate>1999-04-15T00:00:00.0</user:registrationDate>
<user:userType>investor</user:userType>
<user:member>true</user:member>
<user:brokerId>734</user:brokerId>
<user:numberFeatureItems>3</user:numberFeatureItems>
<user:login>sandy</user:login>
30
<user:guests>false</user:guests>
<user:brokers>false</user:brokers>
<user:investors>true</user:investors>
</user:user>
Notice that information about the XML Schema for this data is included in the user:user tag at the beginning
of the document:
xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user
profileMapping+UserProfiles+user.xsd "
The xsi:schemaLocation attribute specifies the URL and name of the Schema file. The Schema
filename (profileMapping+UserProfiles+user.xsd) is determined by the name of the mapping file
(profileMapping.xml), the name of the repository (UserProfiles), and the item descriptor (user). If no
mapping file is used to create the document, the Schema filename indicates the repository and item descriptor.
If you want the Schema filename to include the entire pathname, set the appendRelativeSchemaLocation
property of the GetService component to true. This is especially important if youre using an external Schema
verification tool, which will generally need the complete pathname to find the Schema file.
If you use a mapping file when you create an instance document, you should be sure to supply the name of this
mapping file to the generateXMLSchema command (using the mappingFile argument) when you generate
the Schema. Otherwise the actual Schema filename will not match the name in the xsi:schemaLocation
tag, and the Schema may not accurately reflect the data in the instance document; as a result, you may not
be able to validate the data when reading it into a remote system (or reading it back into Dynamo using
AddService). Note also that if your call to getItemAsXML() includes an input argument that specifies the
names of properties to write out, the Schema will not accurately reflect the data in the instance document, so
validation will not be possible.
To avoid any conflict between tag names, the XML tags in the generated instance document are named
using the convention itemType:propertyName; for example the user:userType tag stores the value
of the userType property of the user item type. If the addItemTypeToPropertyNames property of the
RepositoryXMLTools component that GetService points to is set to true, the tags are named using the
convention itemType:itemType.propertyName; in this case, the tag name would be user:user.userType.
By default addItemTypeToPropertyNames is set to true, because the resulting XML is less likely to result in
naming collisions.
31
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).
32
The application would then use the following code to update the user repository item whose login value is
sandy (assuming the inputXML String contains the instance document shown above):
String[] matchProperties = {"login"};
RepositoryItem updatedItem = UpdateService.updateItem(inputXML,
matchProperties);
Note that UpdateService determines the repository and item type from the namespace of the instance
document. See Getting Repository Items (page 29).
The matchProperties array can contain any number of property names. If the value of each repository item
property named in matchProperties matches its corresponding attribute in the XML instance document, the
item is selected for update. All of the specified properties must match for the item to be selected; for example, if
matchProperties lists login and lastName properties, the values of both properties must match. If multiple
items are selected, an exception is thrown and no update occurs.
Matching is limited to top-level properties of the repository item. Subproperties (such as properties of other
repository items) cannot be matched. So, for example, if a user item has a lastName property that is a String,
you can include lastName in matchProperties; but if a user item has a shippingAddress property that is
another repository item, you cannot include, say, shippingAddress.city in matchProperties.
If a property has been mapped to a different name in the instance document, the name to match on is the
property name used in the repository, not the instance document. For example, suppose you use a mapping file
to map a user items dateOfBirth property to the name birthday, like this:
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="user" default-include="true">
<property name="dateOfBirth" targetName="birthday"/>
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.
33
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user
UserProfiles+user.xsd " ID="user747" repositoryId="user707">
<user:user.emailAddress>sandy@example.com</user:user.emailAddress>
</user:user>
String[] matchProperties = {"repositoryId"};
RepositoryItem updatedItem = UpdateService.updateItem(inputXML,
matchProperties);
In this case, the UpdateService selects the user item whose repositoryId is user707 from /atg/
userprofiling/ProfileAdapterRepository.
Note: Do not confuse with the repositoryId attribute, which identifies a repository item, with the ID attribute
used in the XML schema to identify an XML element. The repositoryId attribute and not the ID attribute is
used to identify which repository item to update.
<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):
The maximum number of matching items is specified by the maxSelectedItems property of RemoveService.
If the number of matching repository items exceeds this value, an exception is thrown. In the /atg/
repository/xml/RemoveService component, maxSelectedItems is set to 5 by default.
34
Security
The content you see as a response to a Web Service call depends on your access privileges. When you login
using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent
Web Service calls in that session are associated with that identity and related role.
For more information on loginUser, see the Personalization Programming Guide. You may also want to learn
how other Web Services handle the security information provided by loginUser. Such information exists in the
Repository Guide and the Core Commerce Programming Guide.
Transactions
When a client calls a Web Service, the transactional behavior of the service is managed entirely on the server
side. The method that is exposed as a Web Service can use standard transaction demarcation techniques, but
the calling client has no control over this.
There are some practical considerations you should be aware of. If a single Web Service call attempts to perform
some operation, and the operation fails, the operation can be rolled back (provided that the Nucleus method
is demarcated properly). However, a transaction cannot span multiple Web Service calls so if an operation
is performed by a sequence of Web Service calls, and the final call fails, there is no way to roll back the steps
performed by the previous calls.
35
Sharing Sessions
When you create a Web Service, you specify whether it should be executed within the context of an HTTP
session. Associating Web Services with a session enables an application to maintain state across Web Service
calls and to use login information for security purposes.
To allow multiple Web Services to share a session, two things need to happen:
1. The Web Service client must allow a session to be shared across certain Web Service calls. To do this, the client
must pass a session cookie between calls.
2. The Web Services themselves must support sessions. When you create custom Web Services, the Web Service
Creation Wizard gives you the option of supporting sessions.
This section includes an example of a helper class that you can use to simplify cookie management. See Writing
a CookieContainer Class (page 37).
RepositoryItems
If your Web Services access RepositoryItems, you need to provide a serializer and deserializer so the
RepositoryItem content can be interpreted by non-Oracle Commerce Platform systems. The following Web
Services transmit content that is natively stored as RepositoryItems:
getProfile
getRepositoryItem
performRQLQuery
getOrderAsXML (Core Commerce users only)
getOrdersAsXML (Core Commerce users only)
getProductXMLById (Core Commerce users only)
getProductXMLByDescription (Core Commerce users only)
getProductXMLByRQL (Core Commerce users only)
getProductSkusXML (Core Commerce users only)
getPromotionsAsXML (Core Commerce users only)
The Oracle Commerce Platform includes several tools for working with RepositoryItems. To make a client able
to serialize and deserialize RepositoryItems, you need to translate the RepositoryItem class into a language
thats native to your client. See Creating a Serializer and Deserializer (page 42) for more information.
36
org.apache.axis.MessageContext;
org.apache.axis.client.Call;
org.apache.axis.client.Stub;
org.apache.axis.transport.http.HTTPConstants;
/**
* A class that can be passed between web service clients that keeps track of
* the cookies received from the server. These cookies are then used by
* subsequent web service client calls in order to ensure that session
* state is maintained.
**/
public class CookieContainer
{
//------------------------------------// Member variables
//------------------------------------/** Array of cookies from the Set-Cookie HTTP header **/
private String[] mCookies = null;
/** Array of cookies from the Set-Cookie2 HTTP header **/
private String[] mCookies2 = null;
//------------------------------------// Methods
//------------------------------------/**
* Gets the cookies set by the Set-Cookie HTTP header
* @return the cookies from the Set-Cookie HTTP header, which
* may be null
**/
public String[] getCookies() {
return mCookies;
}
/**
* Gets the cookies set by the Set-Cookie2 HTTP header
* @return the cookies from the Set-Cookie2 HTTP header, which
* may be null
37
**/
public String[] getCookies2() {
return mCookies2;
}
/**
* Extracts the cookies from the given Axis MessageContext, and
* sets the cookies and cookies2 properties from them.
* @param pContext the Axis message context to examine. This
* cannot be null
**/
public void extractCookies(MessageContext pContext) {
mCookies = (String[])pContext.getProperty
(HTTPConstants.HEADER_COOKIE);
mCookies2 = (String[])pContext.getProperty
(HTTPConstants.HEADER_COOKIE2);
}
/**
* Extracts the cookies from the given Axis Call, and
* sets the cookies and cookies2 properties from them.
* @param pCall the Axis call to examine. This
* cannot be null
**/
public void extractCookies(Call pCall) {
extractCookies(pCall.getMessageContext());
}
/**
* Extracts the cookies from the given Axis Stub, and
* sets the cookies and cookies2 properties from them.
* @param pStub the Axis stub to examine. This
* cannot be null
**/
public void extractCookies(Stub pStub) {
extractCookies(pStub._getCall());
}
/**
* Pushes the cookie values that are set on the instance to
* the given Call
* @param pCall the call to set the cookies on. This cannot be null
**/
public void pushCookies(Call pCall) {
if(mCookies != null)
pCall.setProperty(HTTPConstants.HEADER_COOKIE, mCookies);
if(mCookies2 != null)
pCall.setProperty(HTTPConstants.HEADER_COOKIE2, mCookies2);
}
/**
* Pushes the cookie values that are set on the instance to
* the given Stub
* @param pStub the stub to set the cookies on. This cannot be null
**/
public void pushCookies(Stub pStub) {
if(mCookies != null)
pStub._setProperty(HTTPConstants.HEADER_COOKIE, mCookies);
if(mCookies2 != null)
pStub._setProperty(HTTPConstants.HEADER_COOKIE2, mCookies2);
38
}
}
39
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).
40
41
42
To create a mapping file, you need to know the properties defined by your item descriptor so you can decide
which of them ought to be represented in the XML schema. You can find the location of a Repositorys item
descriptor in the Oracle Commerce Platform Dynamo Server Admin UI:
1. In the Dynamo Server Admin, click the Component Browser link.
2. Navigate to the Repository component that correlates to your Web Service as indicated in the appropriate
documentation for the Web Service.
3. Click the See Property Descriptions link beside the item descriptor name. For the item descriptor name, see
the documentation for your Oracle Commerce Platform applications Web Service.
This list that displays includes all properties that are available to the item descriptor based on the modules
that are currently running.
To make this XML schema compatible with the expectations of the resources that will use it, exclude the
following items from your XML schema:
RepositoryItem properties that accept primitive data types and may be null
RepositoryItem properties that accept Maps, Lists, or Sets
43
Security
The content you see as a response to a Web Service call depends on your access privileges. When you login
using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent
Web Service calls in that session are associated with that identity and related role.
44
For more information on loginUser, see the Personalization Programming Guide. You may also want to learn
how other Web Services handle the security information provided by loginUser. Such information exists in the
Repository Guide and the Core Commerce Programming Guide.
Transactions
When a client calls a Web Service, the transactional behavior of the service is managed entirely on the server
side. The method that is exposed as a Web Service can use standard transaction demarcation techniques, but
the calling client has no control over this.
There are some practical considerations you should be aware of. If a single Web Service call attempts to perform
some operation, and the operation fails, the operation can be rolled back (provided that the Nucleus method
is demarcated properly). However, a transaction cannot span multiple Web Service calls so if an operation
is performed by a sequence of Web Service calls, and the final call fails, there is no way to roll back the steps
performed by the previous calls.
Session Sharing
When you create a Web Service, you specify whether it should be executed within the context of an HTTP
session. Associating Web Services with a session enables an application to maintain state across Web Service
calls and to use login information for security purposes.
To allow multiple Web Services to share a session on .NET, two things need to happen:
1. The Web Service client must allow a session to be shared across Web Service calls. To do this, you need to
define the Web Service calls in the same Web Control and assign a CookieContainer for each call. For
instructions, see Calling Web Services from a .NET Client (page 47).
2. The Web Services themselves must support sessions. When you create custom Web Services, the Web Service
Creation Wizard gives you the option of supporting sessions.
Client Stubs
The Oracle Commerce Platform provides preconfigured client stubs for all Web Services in ATGWS.dll. To use
these stubs you need to install ATGWS.dll. See Installing ATGWS.dll (page 46) for instructions. The client
stubs provided here should be sufficient for your Web Services. Note that simultaneous calls to a Web Service
made by different threads will require that a unique client stub instance exist for each thread.
45
Installing ATGWS.dll
ATGWS.dll is a library that includes a stub class for each Web Service. It also provides the
Atg.DotNet.WebService API used for serializing and deserializing RepositoryItems. All users who want to
access Web Services from a .NET client should install ATGWS.dll. You need two versions of ATGWS.dll on your
system. One version lives in you Global Assembly Cache (GAC) so ASP.NET is able to access it when compiling the
Web Service call. Another version should exist in a location that VS.NET recognizes.
The instructions provided here direct you to use GACutil, a utility provided by .NET, although you can use any
utility that can install ATGWS.dll to the Assembly folder in your windows directory. While the library does not
need to live on the same machine as .NET, .NET needs to be able to access it.
To install ATGWS.dll:
1. Copy <ATG11dir>/DAS/os_specific_files/i486-unknownwin32/ATGWS.dll to your Windows\Assembly folder.
2. Open a command prompt and enter the following command:
<DotNetdir>:\ gacutil/i <ATG11dir>/DAS/os_specific_files/i486-unknownwin32/ATGWS.dll
In this example, <DotNetdir> represents the parent directory, such as c:\DotNet that holds your .NET
software.
Keep in mind that each time you install a new version of ATGWS.dll, it coexists with older versions. The latest
version of ATGWS.dll will instruct the .NET client to use it. Theres no need to uninstall ATGWS.dll when you
want to install a new version. Remember when you do install new versions, you need to update references in
VS.NET to the old version of ATGWS.dll. If youd like to remove all versions of ATGWS.dll, use this command in
a command prompt:
<DotNetdir> gacutil/u <ATG11dir>/DAS/os_specific_files/i486-unknown-
46
win32/ATGWS
You can find the URI for Web Services in the documentation for the specific Web Service:
For Repository Web Services, see the Repository Guide
For Personalization Web Services, see the Personalization Programming Guide
For Commerce Web Services, see the Core Commerce Programming Guide
47
using Atg.DotNet.WebService.Repository.GetRepositoryItem;
// ...
// create stub instance
GetRepositoryItemSEIService getItemClientStub = new
GetRepositoryItemSEIService();
// assign URL of web service
getRepositoryItemClientStub.Url =
"http://example.com/repository/generic/getItem/getRepositoryItem";
// call web service
string itemXml =
getRepositoryItemClientStub.getRepositoryItem("/nucleus/path/to/repository",
"itemDescriptorName", "repositoryId"http://example.com/repository/generic/getItem/
getRepositoryItem
using
using
using
using
using
48
49
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
50
Class Element
Description
constructors
RepositoryItem()
clearPropertyValues
Returns the value provided for a property in the Oracle Commerce Platform. If the
property does not exist, an error of type ATGWS.NoSuchPropertyException is thrown.
setPropertyValue
Property Class
This class represents a given propertys name and value.
51
Class Element
Description
properties
Dirty
XML data type that will be used to represent the propertys value.
constructor
Property()
getName
RepositoryItemRef Class
This class represents a reference to another RepositoryItem.
Class Element
Description
properties
RepositoryName
setRepositoryItem
Initializes the ItemRef to refer to the provided RepositoryItem.
52
Class Element
Description
properties
TypeName
Name of any properties that are either deserialized from or serialized into the complex
type.
constructor
ComplexType()
getPropertyValue
Retrieves values from the Oracle Commerce Platform for the specified properties. If the
property does not exist, an error of type ATGWS.NoSuchPropertyException is thrown.
setPropertyValue
NoSuchPropertyException Class
This class generates an exception each time a getProperty or getPropertyValue method tries to interact
with a property that has not been specified for the designated RepositoryItem.
Class Element
Description
property
PropertyName
NoSuchPropertyException
RepositoryItemSerializer Class
This class conducts serialization/deserialization and permits you to decide if you want all or only dirty properties
to be updated.
53
Class Element
Description
constructors
RepositoryItemSerializer()
deserialize (string)
should be deserialized.
RepositoryItemSerializationException Class
This class creates an exception object when errors occur during serialization or deserialization.
Class Element
Description
constructor
RepositoryItemSerializationException()
54
This section provides information about and instructions for using the Oracle Commerce Platform
Representational State Transfer (REST) Web Services.
Oracle Commerce Platform REST Web Services provide access to Nucleus components. Nucleus components
are server-side JavaBeans and servlets that perform the back-end functionality of a Web application, such as
enabling database connectivity, logging, scheduling, and handling HTTP requests.
Oracle Commerce Platform previously provided a single process that wrote directly to the HTTP response buffer.
This API is identified throughout this guide as the Legacy REST API. The Legacy framework has been enhanced
to provide a Model View Controller (MVC) architecture and framework that supports multiple controllers that
generate a model map that can be filtered. This multiple controller API is known as the REST MVC API.
Note: It is strongly suggested that, if you are creating new REST services, you use the REST MVC API. The Legacy
REST API is limited in its ability to be configured and is not extensible.
This section is divided into three parts:
Introduction to REST Web Services (this section) describes generic REST Web Services and terminology. This
section also provides information that applies to both the REST MVC Web Services and the Legacy REST Web
Services
Part I, Oracle Commerce Platform REST MVC Web Services (page 67) describes the extensible REST MVC
API, describing the architecture and components that allow you to create REST services, as well as instructions
on creating your own REST services. This section also provides detailed examples of REST services that have
been provided for quick implementation
Part II, Legacy REST Web Services (page 315) describes the Legacy REST API and the components that are
used to develop REST services
55
The portion of the application path following /rest/ identifies which version of the Oracle Commerce Platform
REST framework type you are using.
The REST MVC framework uses /model, for example:
http://servername:port/rest/model/atg/commerce/order/purchase/
CartModifierActor/addItemToOrder
For additional information, refer to The REST MVC Definition Framework (page 71) section.
The Legacy REST framework uses /bean, /repository or /service, depending on the component used. For
example:
http://servername:port/rest/bean/atg/userprofiling/ProfileServices/
loginUser?arg1=MyUsername&arg2=MyPassword
http://servername:port/rest/repository/atg/userprofiling/
ProfileAdapterRepository/user
For additional information, refer to the Using Legacy REST Web Services (page 317) section. For additional
information on component paths, refer to the Platform Programming Guide.
URLs can supply additional data to the REST Web Service using parameters or form post data. By setting control
parameters, as described in the Adding Control Parameters (page 61) section, or standard query and/or post
56
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.
Method
Explanation
GET
POST
Use this method to invoke functionality or make changes to your Oracle Commerce Platform
server.
For example, you may invoke methods, update Nucleus component properties, and create
repository items.
PUT
(Legacy REST Only) Use this method to make changes to your Oracle Commerce Platform
servers.
For example, you may update repository item and Nucleus component property values.
DELETE
For additional information on these and other HTTP methods, refer to the W3 definitions, available at http://
www.w3.org.
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.
57
Code
Description
The request could not be completed because the request URL and/or
parameters were improperly formatted.
401 (Unauthorized)
The user session does not have the proper security credentials to execute the
method, property, or access the repository for the requested resource.
403 (Forbidden)
The specified property has been configured as not writeable via the filtering
configuration.
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.
For additional information on these and other HTTP status codes, refer to the W3 definitions, available at http://
www.w3.org.
Returning Data
Oracle Commerce Platform REST Web Services returns the results of operations that you perform in an HTTP
response message body. The output data can be returned in either JavaScript Object Notation (JSON) or
eXtensible Markup Language (XML) format.
The following example shows output data in JSON format.
{"password": "280001"}
<password>280001</password>
You can configure your return output data to be provided in the format you choose by setting the default return
output type on the REST server. Additionally, using the atg-rest-output command, you can override the
default output type. Refer to the Adding Control Parameters (page 61) section for additional information.
For information on configuring output in REST MVC, refer to the Configuring REST MVC Output (page 109)
section. For information on configuring output in Legacy REST, refer to the Returned Data in Legacy REST (page
331) section.
58
59
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.
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.
{
"shippingGroups": {"Test": {
"specialInstructions": {},
"priceInfo": {
"amount": 0,
"currencyCode": null,
"amountIsFinal": false,
"discounted": false
},
"description": "sg140012",
"actualShipDate": null,
"submittedDate": null,
"state": 0,
"locationId": null,
"shipOnDate": null,
"shippingMethod": "hardgoodShippingGroup",
60
Component
Explanation
curl
Names the program being invoked. The manner in which you invoke the cURL commandline tool depends on how it has been installed in your environment.
-L
Identifies an HTTP Location. If the server reports that the requested page has moved to a
different location (indicated with a Location: header and a 3XX response code), this option
will make cURL redo the request at the new location.
-v
Writes verbose output while sending and receiving HTTP messages. This option exposes
more details of the HTTP transaction.
-b
Uses cookies stored in the specified file to authenticate the client. In Legacy REST Web
Services, cookies are stored in a file named cookies.txt. The customer_cookies.txt
file is used for external REST MVC calls, and the agent_cookies.txt file is used for agentbased internal REST MVC calls.
A session identifier must be stored in the file. When cURL logs into the REST Web Services,
the cookies.txt instructs it to write the cookies it receives in that file.
-c
This command line option activates the cookie engine that makes cURL record and use
cookies. You can also activate cookies by using the -b cookie option. Using c provides
the HTTP cookie file where cURL writes all cookies after a completed operation. cURL
writes all cookies previously read from a specified file, as well as all cookies received from
remote server(s). If no cookies are identified, no file will be written.
-X
Use the specified HTTP method when communicating with the REST Web Services.
-H
Include the specified Content-Type declaration in the HTTP request header. This describes
the nature of the data in the message body of the HTTP request.
-d
Include the following content in the message body of the HTTP request.
URL
The URL of the REST Web Service that is used in the example.
Note: The HTTP transactions shown in the examples in this document may include specific details of the testing
environment used to produce them. Some details may differ in the HTTP transactions you conduct with the
REST Web Services. For example, the application server version identifiers shown in the HTTP transaction may
not match the application that your Oracle Commerce Platform server uses.
61
You can include control parameters either in the URL for the REST Web Service or in the message body of a POST
or PUT request.
Note: Several control parameters have equivalent configuration properties. Set these configuration properties
to control the way that REST MVC Web Services are processed by default. See The REST MVC Definition
Framework (page 71).
The following table explains the control parameters recognized by the REST Web Services server. This table also
identifies if the parameter is used in the Legacy REST Web Services or the REST MVC Web Services.
Parameter
REST Version
Explanation
atg-rest-append-multivalues
Legacy Only
atg-rest-classdescriptor
Both Legacy
and MVC
atg-rest-class-type
Both Legacy
and MVC
atg-rest-count
Legacy Only
atg-rest-depth
Legacy Only
atg-rest-form-tagpriorities
Legacy Only
atg-rest-http-method
Legacy Only
atg-rest-index
Legacy Only
62
Parameter
REST Version
Explanation
atg-rest-input
Both Legacy
and MVC
atg-rest-json-input
Legacy Only
atg-rest-method
Legacy Only
atg-rest-null
Both Legacy
and MVC
atg-rest-output
Both Legacy
and MVC
atg-rest-param-classtypes
Both Legacy
and MVC
Use the key-class attribute when the containerclass implements java.util.Map. For example:
{'container-class':'java.util.HashMap',
'key-class':'java.lang.String',
'element-class':'java.lang.String'}
atg-rest-propertyfilters
Legacy Only
atg-rest-propertyfilter-templates
Legacy Only
63
Parameter
REST Version
Explanation
atg-rest-return-formhandler-exceptions
Legacy Only
atg-rest-return-formhandler-properties
Legacy Only
atg-rest-rql
Legacy Only
atg-rest-simpleresponse-codes
Legacy Only
atg-rest-transient
Legacy Only
atg-rest-user-input
Both Legacy
and MVC
64
http://localhost:8280/rest/model/atg/userprofiling/ProfileActor/
login?login=JohnDoe@example.com&password=1234&atg-rest-user-input=MyMessageId
The Oracle Commerce Platform REST Web Services server can interpret message body parameters in one of the
following three markup formats. Make sure you set the correct Content-Type value for the markup that you
use.
XML
JSON
URL query string in Legacy REST
Note: The Legacy REST Web Services server will only accept parameters in the message body of a POST or
PUT HTTP request. If you need to use the GET or DELETE methods, you need to include data with your request,
and you cannot include URL parameters, use the atg-rest-view and atg-rest-http-method control
parameters. See Handling POST Requests as Other Methods (page 318).
65
66
Array Type
Java Notation
String
[Ljava.lang.String;
byte
[B
int
[I
[[Ljava.lang.String;
The following section describes the installation and configuration of the REST server.
69
registeredUrls+=\
/atg/userprofiling/ProfileActor/login,\
/atg/userprofiling/ProfileActor/login-success,\
/atg/userprofiling/ProfileActor/login-error,\
Note that if you enter only the actor, the default actor-chain will be used.
3. Save the file.
Note: If you do not register the actor-chain, when the actor-chain is used in a REST Web Service, an error will
occur.
70
REST MVC Web Services allow you to use HTTP requests to work with any Oracle Commerce Platform
application. These services provide you with ways to do things such as protect user logins, send data to forms
using mobile applications, or retrieve data from search results. Multiple controllers generate a model map that
can be filtered, and the output from these controllers is used to generate a JSON or XML response.
The REST MVC API can be extended or customized as needed. The following information describes the
components of the API, and provide examples that may be useful when creating custom elements for your
environment.
Architecture Overview
When you initiate a REST MVC service, you send a URL. This URL must be explicitly defined and registered
with the REST MVC Services. If registered, as outlined in the Enabling REST Services (page 69) section, the URL
references controllers, which are known as actors. Each actor, which is configured using XML definition files,
interfaces with a resource, such as a JSP page, a form handler, a servlet bean, a Nucleus component or another
chain of actors, or actor-.
These actors generate a ModelMap, which can be filtered and transformed as necessary. The ModelMap is a map
of maps that is populated by actors. The response that is rendered is based on the content that the ModelMap
has generated. ModelMap instances are created by the ModelMapFactory.
Each time that an actor is invoked, an ActorContext is passed into the actor. An ActorContext, which is
created by an ActorContextFactory, is a map of attributes that are relevant to the context in which an actor is
involved.
REST MVC resolves Nucleus components using the ActorChainService, which uses an XML definition file to
define both the chains of actors to execute, and the order in which they must be executed.
Once all the actors have generated their model data, bean filters are applied to the data. Then the response
generator uses the ModelMap to generate a JSON or XML response.
71
1. The REST Service uses a URL that begins with /rest/model and has been registered with the
ActorChainRestRegistry service. In this example, the URL is:
/rest/model/atg/commerce/order/purchase/CartModifierActor/addItemToOrder
This URL contains not only the CartModifierActor Nucleus component, but the addItemToOrder actorchain.
The REST Service also verifies the users access using the AccessControllerService.
2. The REST Service initializes the actor context from the REST control parameters and the URL. The actorcontext is then passed to the ActorChainService. Because the addItemToOrder actor-chain calls /atg/
commerce/order/purchase/
CartModifierFormHandler, a formActor is invoked. The /atg/commerce/order/ShoppingCart
component is invoked by the componentActor. Refer to the XML Definition Elements (page 73) section
Actor Types
The REST MVC APIs modular and extensible functionality is based on actors, which uses a number of different
types of actors to perform a variety of functions. The atg.service.actor.Actor interface contains the
72
following actor types that perform specific actions or provide configurations. For detailed information on any of
these classes, refer to the ATG Platform API Reference.
Component Actor Use this actor to set component property values or invoke methods on a component, or
to read component property values
Droplet Actor Use this actor when you want to invoke droplets and output data from the droplet to the
ModelMap. Inputs are mapped to the droplet input parameter. Other types of actors can be nested in the
oparam parameter of a DropletActor
Form Actor Use this actor to set up form handler inputs and submit a form
JSP Actor This actor invokes a JSP page and adds the JSP response or JSP-defined variables to the ModelMap
Nested Actor These actors allow you to invoke actor-chains from within other actor-chains, helping to define
modular units of work that can be combined and extended
Variable Actor The VarActor enables you to set variables in the actor context
Request URLs
Oracle Commerce Platform REST MVC requests use a /rest/model URL to process requests against the actor
framework. The general format for a REST MVC URL is:
http://host:port/rest/model/actor_chain_component/tail
Refer to the External REST MVC Service Call Examples (page 115) and Internal REST MVC Service Call
Examples (page 177) sections to see examples of request URLs in cURL.
73
74
<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>
Attribute/Elements
Description
id
Required. Defines the chain-id. This attribute is used during the XML combination
process, and identifies the chain to execute.
transaction
Provides transaction demarcation for the chain. For information on the supported
transaction demarcation types, refer to the Repository Guide. The default value is
TX_SUPPORTS.
Note: If you are creating REST MVC Service calls it is important to note that Profile
and Order-related form handlers require that the transaction be TX_SUPPORTS and
not TX_REQUIRED, as the transaction must be initiated in the form handler and not
be defined prior.
actors
An actor-chain can have one or more actors that include input and/or output
elements.
You can use the Dynamo Server Admin to review actors, actor-chains and their attributes.
Attribute/Element
Description
id
Required. The actor ID. This attribute is used for actor ordering.
75
Attribute/Element
Description
name
return-model-var
Provides the variable name of the child actor-chain returned by the ModelMap. The
ModelMap that is returned from the child actor-chain can be accessed using this
variable name.
chain-id
depends
This element defines actors that must be executed prior to the execution of the
current actor. There can be multiple depends elements associated with an actor.
depends-ifpresent
This element defines actors that, if present, must be executed prior to the execution
of the current actor. There can be multiple depends-if-present elements
associated with an actor.
input
This element defines each actors input. Actors can have multiple input elements.
output
This element defines each actors output. Output elements create a map entry in a
ModelMap. Actors can have multiple output elements.
The ActorContext and ModelMap of the parent actor are not passed to the child actor. The following example
shows how information can be passed from a child actor-chain to a parent actor-chain. Note that request
parameters do not need to be passed in explicitly as inputs; you can pass in their variables:
In the above example, the parent actor-chain contains a quantity ModelMap entry. Map entries are based upon
the child actor-chain. For information on working with implicit objects, which can be used in any chain, refer to
the Working with Implicit Objects (page 98) section.
To pass the entire child ModelMap back to the parent and not have it nested under another variable name,
use the add-map-children="true" in the output element to copy the child ModelMap keys to the parent
ModelMap.
76
Attribute/Element
Description
name
id
Required. This attribute defines the actor ID, and is used for actor ordering.
method
Identifies the name of the method to be executed. Use only when invoking a
method.
component-var
method-return-var
Identifies the variable name that accesses the method invocations returned
value.
set-propertyrequires-sessionconfirmation
invoke-methodrequires-sessionconfirmation
By default, all method calls require session confirmation numbers. This property
is set to true by default.
depends
This element defines actors that must be executed prior to the execution of the
current actor. There can be multiple depends elements associated with an actor.
depends-if-present
This element defines actors that, if present, must be executed prior to the
execution of the current actor. There can be multiple depends-if-present
elements associated with an actor
input
This element defines each actors input. Actors can have multiple input
elements.
output
This element defines each actors output. Output elements create a map entry
in a ModelMap. Actors can have multiple output elements.
77
</component>
Note that you can reference a component without having to invoke a component actor. The following example
shows how you would resolve the orderID component in-line. This works for components that are referenced
only once; if you plan to reference the same component multiple times, it is best to define the variable, as in the
above example:
<input name="ordered" value="${nucleus['/atg/userprofiling/
ActiveCustomerProfile'].orderId}"/>
78
value="${nucleus['/atg/userprofiling/Profile']}"/>
<input name="parameters" class-name="java.util.Map" index="3" value="${null}"/>
</component>
Note that the following class-name values are used to identify primitive array types:
Class-Name Value
char
short
double
long
79
Class-Name Value
boolean
byte
float
int
<actor-chain-id=getCommerceIdentifierPaymentInfos">
<component id="paymentGroupFormHandler"
name="/atg/commerce/order/pruchase/PaymentGroupFormHandler
component-var="paymentGroupFormHandler">
<input name="listId" value="${param.listId}" priority="1000" />
<output id="currentList" name="currentList"
value="${paymentGroupFormHandler.currentList}" />
</component>
</actor-chain>
80
By default ComponentActors use Dynamo session confirmation numbers, _dynSessConf, for method calls and
setting property values. However, session confirmation numbers are not required for calls such as outputting
properties of a component, a JSPActor or a DropletActor. For detailed information on Dynamo Session
Confirmation Numbers, refer to the Platform Programming Guide.
The following example shows how to disable session confirmation numbers for method calls:
Attribute/Element
Description
name
Required. This is the Nucleus path of the Oracle Commerce Platform servlet bean.
id
Required. This attribute defines the actor ID, and is used for actor ordering.
var
oparam
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.
81
Attribute/Element
Description
depends-ifpresent
This element defines actors that, if present, must be executed prior to the execution
of the current actor. There can be multiple depends-if-present elements
associated with an actor.
input
This element defines each actors input. Actors can have multiple input elements.
output
This element defines each actors output. output elements create a map entry in a
ModelMap. Actors can have multiple output elements.
DropletActors can be nested with all types of actors using the oparam element.
Attribute/Element
Description
name
actors
The oparam element can have one or more actors that include output or set-var
elements.
82
<actor-chain>
<droplet path="/atg/store/droplet/StoreLookupDroplet" var="storeLookup">
<oparam name="output">
<droplet path="/atg/store/droplet/StoreSiteFilterDroplet"
var="storeSiteFilter">
<!-read 'items' from StoreLookupDroplet -->
<input name="collection" value="${storeLookup.items}"/>
<!-output array of stores for the current site -->
<oparam name="output">
<output name="stores" value="${storeSiteFilter.filteredCollections}"/>
</oparam>
</droplet>
</oparam>
</droplet>
</actor-chain>
Because each actor-chain has its own ActorContext and ModelMap, you can use the input and output of
nested actors to pass inputs into a nested ActorContext and return outputs from nested ModelMaps. In the
following example, the add-map-children attribute copies the properties in the nested ModelMap to the outer
ModelMap:
</actor-chain><actor-chain id="addItemToOrder-success">
<actor id="order" name="/atg/commerce/ShoppingCartActor"
chain=id="detailed" return-model-var="model">
<output id="model" add-map-children="true" value="${model}"/>
</actor>
</actor-chain>
Note that you should make your actors accessible from either the client, using the request parameter, or from
the nested actor, using the variable. Clients pass actors as param, for example param.orderId. Nested actors
pass their variables as ActorContext variables. You must configure your input to look for both param and
ActorContex variables. For example:
<dsp:importbean
bean="/atg/svc/agent/ui/formhandlers/CustomerSearchTreeQueryFormHandler"
scope="request" />
<dsp:droplet name="/atg/droplet/Switch">
<param name="value" bean="CustomerSearchTreeQueryFormHandler.pagesAvailable"/>
83
<oparam name="0">
<!-perform an action -->
</oparam>
</dsp:droplet>
There is no bean attribute available for DropletActors. Instead, you can retrieve servlet beans using the
$nucleus syntax. For example:
<droplet name="/atg/droplet/Switch">
<input name="value" value="${nucleus[/atg/svc/agent/ui/formhandlers/
CustomerSearchTreeQueryFormHandler].pagesAvailable}"/>
<oparam name="0">
<!-perform an action -->
</oparam>
</dsp:droplet>
84
Attribute/Element
Description
name
Attribute/Element
Description
handle
id
Required. This attribute defines the actor ID, and is used for actor ordering.
var
The variable name that can access form handler properties and exceptions.
requires-sessionconfirmation
depends
This element defines actors that must be executed prior to the execution of
the current actor. There can be multiple depends elements associated with an
actor.
depends-if-present
This element defines actors that, if present, must be executed prior to the
execution of the current actor. There can be multiple depends-ifpresent elements associated with an actor.
input
This element defines each actors input. Actors can have multiple input
elements.
output
This element defines each actors output. Output elements create a map entry
in a ModelMap. Actors can have multiple output elements.
use-forwards
The following is an example of a form element that adds a single item to an order:
<!-- This chain is used to add a single item to an order -->
<actor-chain id="addItemToOrder" transaction="TX_SUPPORTS">
<form id="cartModifierFormHandler" name="/atg/commerce/order/purchase/
CartModifierFormHandler" var="cartModifierFormHandler"
handle="addItemToOrder">
<input name="catalogRefIds" value="${param.catalogRefIds}">
<tag-converter class-name="atg.droplet.ArrayTagConverter"/>
</input>
<input name="productId" value="${param.productId}"/>
<input name="quantity" value="${param.quantity}"/>
<input name="locationId" value="${param.locationId}"/>
<input name="siteId" value="${param.siteId}"/>
<!-- optional giftlistId/giftlistItemId are set if the item is added from a
giftlist -->
<input name="giftlistId" value="${param.addToWishlist ?
nucleus['/atg/userprofiling/Profile'].wishlist.repositoryId :
param.giftlistId}"/>
<input name="giftlistItemId" value="${param.giftlistItemId}"/>
<input name="addItemToOrderErrorURL" value="/model/atg/commerce/order/
purchase/CartModifierActor/addItemToOrder-error"/>
<input name="addItemToOrderSuccessURL" value="/model/atg/commerce/order/
purchase/CartModifierActor/addItemToOrder-success"/>
</form>
</actor-chain>
85
By default, all form elements define success and error chains. You can use XML combining to modify the default
behavior of the chains. The following example shows what you would create to make a combined file that
modifies the addItemToOrder-success chain:
<actor-chain id="addItemToOrder-success">
<actor id="order" name="/atg/commerce/ShoppingCartActor" chain-id="summary"
return-model-var="model">
<output id="model" add-map-children="true" value=${model}" />
</actor>
</actor-chain>
The success or error URL, if present, is generally a REST URL that references another actor that generates the next
page. Success and error URL are specified by the actor definition. Your success and error URLs should start with
/model/atg if you are forwarding. If you are doing a redirect, start your URLs with /rest/model/atg. The
FormActor uses the use-forward attribute. Note that it is better to use forwarding than redirection.
When using a FormActor, use the priority attribute to initialize input array size before the array is populated
if you are passing input arrays. For example:
86
</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}"/>
87
<form id="profileFormHandler-login"
name="/atg/userprofiling/ProfileFormHandler" handle="login"
var="profileFormHandler" requires-session-confirmation="false">
<input name="value.login" value="${param.login}" />
<input name="value.password" value="${param.password}" />
<input name="loginErrorURL"
value="/rest/model/atg/userprofiling/ProfileActor/login-error"/>
<input name="loginSuccessURL"
value="/rest/model/atg/userprofiling/ProfileActor/login-success"/>
</form>
</actor-chain>
88
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.
{
"formError":true,
"formExceptions":[{
"localizedMessage":"There was an error updating this order",
"cause":null,
}],
"concurrentUpdate":false
}
For Oracle Commerce Platform-based form handlers, the form handler response is similar to the following:
89
Attribute
Description
id
Required. This attribute defines the actor ID, and is used for actor ordering.
page
Required. This is the absolute path of the JSP URL, excluding the context root.
context
response-var
The value that is written to the HTTP response by the JSP page. You can reference
this attribute in an output element to add the response to the output model. This
is useful for returning HTML snippets to render.
depends
This element defines actors that must be executed prior to the execution of the
current actor. There can be multiple depends elements associated with an actor.
depends-ifpresent
This element defines actors that, if present, must be executed prior to the execution
of the current actor. There can be multiple depends-if-present elements
associated with an actor.
input
This element defines each actors input. Actors can have multiple input elements.
output
This element defines each actors output. Output elements create a map entry in a
ModelMap. Actors can have multiple output elements.
90
91
92
Attribute/Element
Description
id
Required. This attribute defines the actor ID, and is used for actor ordering.
name
Defines the name of the map entry. The value of this attribute can be static, or a
dynamic EL expression. For additional information on ActorContext variables,
refer to the Working with Implicit Objects (page 98) section.
value
Defines the value of the map entry. The value of this attribute can be static, or a
dynamic EL expression. For additional information on ActorContext variables,
refer to the Working with Implicit Objects (page 98) section.
filter-id
Defines the bean filter that will be applied when the value object is filtered
using the BeanFilterService. Note that the filter-id attribute on a bean
filter property will override this filter-id attribute.
embed-for-mime-type
Identifies if the value of the object should be embedded within the server
response. For example, if the object is a JSON string, and it should be embedded
in the JSON response, set the embedded mime attribute to application/
json. If the ResponseGenerator has been set to output as JSON, the string
is added to the JSON response. If the EmbeddedMimeType does not match the
response mime type, (for example, the response mime type is set to XML), the
JSON response will be encoded as a string inside the XML response.
add-map-children
This attribute, when set to true, copies the key/value pairs of a map value into
the ModelMap. The value must be a map. This attribute is often used to pass the
values of a child ModelMap to a parent ModelMap in a nested actor call.
depends
This element defines actors that must be executed prior to the execution of the
current actor. There can be multiple depends elements associated with an actor.
depends-if-present
This element defines actors that, if present, must be executed prior to the
execution of the current actor. There can be multiple depends-if-present
elements associated with an actor.
message
The output tag supports internationalized messages that are added to the
ModelMap.
The filter-id identifies the filter for the BeanFilterService to apply. Refer to the Bean Filtering (page
101) section for further information.
The output tag supports localized message tags, which add internationalized messages to the ModelMap. By
default, all messages are localized based upon the current users locale, however, the locale can be passed in
using the message tag.
The message element contains the following:
Attribute/Element
Description
id
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
key
message-param
If message parameters are required during the resource lookup, you can use the
attributes used by this element:
id The ID of the message param.
value The value to pass.
The following is an example of an output element with a message element. Messages are, by default, localized
using the users locale, however, you can set the locale using the message tag:
{"error": {
"messageCode" : "PRODUCT_NOT_IN_CURRENT_CATALOG",
"localizedMessage" : "Product xprod2099 is not defined in the current catalog"
}}
93
Attribute/Element
Description
name
value
property-editor
In certain actors, a property editor is used to modify the JSON or XML value into
a complex object. Refer to The Component Element (page 77) section for
information on working with property editors.
tag-converter
Use this element to coerce the JSON or XML value into a complex object using the
class-name attribute.
priority
array-size
Used only by the FormActor, this attribute is used to support form handler
array support. Refer to The Form Element (page 84) section for additional
information.
index
Used only by the ComponentActor in a method call, this attribute defines the
order of the methods parameters. Refer to The Component Element (page 77)
section for additional information on this attribute.
94
Ordering Actors
The depends and the depends-if-present elements control actor-chain ordering. If your actors are defined
in a single file, the order in which you define your actors is the way they will be executed. However, if you
have actors that you have defined in various overriding layers and you want to change their order, you must
identify the order using the depends and depends-if-present elements. If actor order is not important, these
elements are not required in the actor definition. For example, if you have a base configuration file for shipping
groups:
<actor-template>
<droplet id="ApplicableShippingGroups" name="/atg/commerce/custsvc/
order/ApplicableShippingGroups" var="applicableShippingGroups">
<!-- The ShippingGroupDroplet must be initialized before the
ApplicableShippingGroups droplet can be invoked -->
<input name="order" value="${nucleus["/atg/commerce/custsvc/environment/
CSREnvironmentTools"].currentOrder}"/>
<oparam name="output">
<output name="shippingAddresses" value="${applicableShippingGroups.
shippingGroups}" filter-id="shippingAddress"/>
</oparam>
</droplet>
</actor-chain>
<actor-template>
The file that you would create in your local configuration directory to order actors would contain:
<actor-template>
<actor-chain id="shippingAddresses" transaction="TX_SUPPORTS">
<droplet id="ShippingGroupDroplet"
name="/atg/commerce/custsvc/order/ShippingGroupDroplet">
<input name="clear" value="${param.init}"/>
<input name="initShippingGroups" value="${param.init}"/>
<input name="initShippingInfos" value="${param.init}"/>
<input name="initBasedOnOrder" value="${param.init}"/>
<input name="shippingGroupTypes"
value="${nucleus\["/atg/commerce/custsvc/util/CSRConfigurator"\].
shippingGroupTypesToBeInitialized"/>
</droplet>
<droplet id="ApplicableShippingGroups">
<!-The ShippingGroupDroplet must be initialized before the
ApplicableShippingGroups droplet can be invoked -->
<depends id="ShippingGroupDroplet"/>
</droplet>
</actor-chain>
<actor-template>
In this example, the ShippingGroupDroplet initializes the shipping group information. However, because
it must be invoked before running the ApplicableShippingGroups droplet, you must define a depends
element, indicating that the ShippingGroupDroplet should be executed first.
95
Attribute/Element
Description
id
Required. The actor ID. This attribute is used for actor ordering.
name
Required. The name of the map entry. This can be a static or dynamic EL
expression.
value
This attribute defines the value of the map entry, and can be a static or dynamic
EL expression.
depends
This element defines actors that must be executed prior to the execution of the
current actor. There can be multiple depends elements associated with an actor.
depends-if-present
This element defines actors that, if present, must be executed prior to the
execution of the current actor. There can be multiple depends-if-present
elements associated with an actor.
In this example, the set-var element sets the environmentChangeState variable in the actor context while
executing the first output.
96
$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>
97
<output name="shippingAddresses"
value="${applicableShippingGroupsParams.shippingAddress}"
filter-id="shippingAddress"/>
</oparam>
</droplet>
</actor-chain>
<actor-template>
98
Object
Description
atgActorModel
Maps the current actor-chains modelMap. This does not reference the parent
chains modelMap.
cookie.name
header.name
headerValues.name
nucleus
objectParam.name
param.name
paramValues.name
request
session
If a variable name does not start one of the implicit objects listed in the Working with Implicit Objects (page
98) section, the system will look up the variable in the attributes of the ActorContext, then in the attributes
of the request and finally in the attributes of the session. Note that you should have a separate actor context per
actor-chain.
When working with a JSP page and JSPActors, the JSP c:set tag saves the variable in a request or session
attribute. The attributes that are set using the c:set tag are accessible in the actor definition and can be
referenced in an output element to include in the ModelMap.
99
The output from this call would be the following, which identifies that the REST class-type is a HashMap.:
{
"atg-rest-class-type":\"java.util.HashMap\",
"atg-rest-values":{
"agentId": \"agent007\",
"providerNote": \"Quote good until 11/11/14\",
"externalId": \"external001\",
"expirationDate": \"2014-11-11 11:00\",
"orderAdjustment": \"5.0\",
}
}
100
Element
Match Attribute
actor
id
actor-chain
id
component
id
depends
id
depends-if-present
id
droplet
id
form
id
input
name
Element
Match Attribute
jsp
id
message
id
message-param
id
oparam
name
output
id
Bean Filtering
The BeanFilterService filters the properties of a java bean or repository item and converts beans into a map
of properties. The BeanFilterService reads XML definition files that define which properties of a Java class or
repository item should be included in the filtered view of the object. The XML definitions include ways to remap
property names and transform properties.
By default, the BeanFilterService is applied to the ModelMap by the REST MVC framework before
generating a JSON or XML response. However, you can filter objects at any time. For example, you can use the
BeanFilterService as a ComponentActor to filter a repository item before adding it to the ModelMap. This
converts the repository item into a map of primitive objects:
<component name="/atg/dynamo/service/filter/bean/BeanFilterSerivce"
method="applyFilter" method-return-var="rtn">
<input name="pTargetObject" value="${myRepositoryItem}" />
<output name="myRepositoryItem" value="{rtn}" />
</component>
There are two types of bean filters, those for repository items and those for Java bean classes. By using the
ComponentActor, you can add a component to the ModelMap, which can then be filtered by the class that the
component implements. For example:
<actor-template>
<actor-chain>
<component id="profile" name="/atg/userprofiling/Profile"
component-var="profile">
<output name="profile" value="${profile}" />
</component>
</actor-chain>
</actor-template>
<bean-filtering>
<bean type="atg.userprofiling.Profile">
<filter id="default">
101
Bean filters combine filter definitions from all classes or interfaces for an object using the filter-id property.
You can also include other bean filters within a bean filter by using the include-filter attribute.
It is best to define afilter for every object, so that you can control its output. Note that if an object has no filters
defined, it will output all properties.
The following XML values are defined by the atg/dtds/beanfilter/beanFiltering_1.0.dtd file:
Attribute
Description
name
default-filter
The ID of the default filter. If no default-filter is defined, the first filter is used.
Available Filters
There are three filters that are primarily used:
detailed This filter provides a detailed list
short This filter provides a short list
summary This filter provides a summary
The following is an example of the ElectronicShippingGroup filter:
<bean type="atg.commerce.order.ElectronicShippingGroup>
<filter id="summary">
<property name="emailAddress"/>
<property name="shippingAddress" hidden="true"/>
</filter>
102
</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.
<bean type="atg.commerce.order.ShippingGroup">
<filter id="summary">
<property name="actualShipDate"/>
<property name="id"/>
<property name="shipOnDate"/>
<property name="shippingAddress"/>
<property name="shippingGroupClassType"/>
<property name="shippingMethod"/>
<property name="specialInstructions"/>
<property name="stateAsUserResource"/>
<property name="stateDetail"/>
<property name="submittedDate"/>
<property name="trackingNumber"/>
</filter>
</bean>
<bean type="atg.commerce.order.ElectronicShippingGroup>
<filter id="summary">
<property name="emailAddress"/>
<property name="shippingAddress" hidden="true"/>
</filter>
<component>
<!-<bean type="atg.commerce.order.HardgoodShippingGroup"
super-type="atg.commerce.order.ShippingGroup"/> -- >
</bean>
103
Attribute
Description
id
The identifier for the filter when it is referenced by another filter, a default filter
setting or another actor.
include-filter
Identifies the filter that is included in the property definition. The inclusion occurs at
all levels of the class hierarchy.
default-include
Identifies whether or not to include all of the standard properties when obtaining
values for this component. The default is false, where only filtered properties will
be included.
<bean-filtering>
<repository name="/atg/commerce/catalog/ProductCatalog">
<item-descriptor="product" default-filter="full">
<filter id="detailed">
<property name="repositoryId" target="id"/>
<property name="displayName"/>
<property name="longDescription"/>
<property name="productDescription" target="description"/>
<property name="thumbnailImage" target="thumbnailImage.url"/>
<property name="fullImage" target="fullImage.url"/>
<property name="largeImage" target="largeImage.url"/>
<property name="relatedProducts" property-customizer=""
filter-id="summary"/>
</filter>
<!-For related products we only want to output a small set of properties
about the related products -->
<filter id="shortSummary">
<property name="repositoryId" target="id"/>
<property name="displayName"/>
<property name="thumbnailImage" target="thumbnailImage.url"/>
</filter>
</item-descriptor>
</repository>
Note that the filter-id attribute of the filter element supersedes any filters that may have been applied in
the actor output definition.
104
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.
Attribute
Description
name
The name that the property will use when sending the response.
105
Attribute
Description
target
The name of the property that is read from the Java servlet bean or repository. If
no target is supplied, the value of the name attribute will be used instead.
propertycustomizer
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.
106
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'" />
Attribute
Description
name
value
Passing name and value attributes into a property-customizer is similar to passing attributes into a custom
repository-descriptor. For example, you can update the maskedCreditCardNumber property that was
created in The Property Element (page 105) section to identify the number of digits that are not masked when
displaying a credit card number:
<property name="maskedCreditCardNumber" property-customizer="/atg/rest/filtering/
customizers/CreditCardNumberProeprtyCustomizer">
<attribute name="unmaskedLength" value="4" />
</property>
By creating this new attribute, when the credit card information is rendered, all but the last four numbers will be
masked.
Attribute
Description
name
item-descriptor
107
<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.
Attribute
Description
name
default-filter
The ID of the default filter for this item-descriptor. If you define more than one
filter, specify a default filter to avoid errors in the case where no filter is specified in
the ModelMap.
<repository name="/atg/multisite/SiteRepository">
<item-descriptor name="siteConfiguration">
<filter id="short">
<property name="id" />
<property name="name" />
</filter>
</item-descriptor>
</repository>
108
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.
Property
Description
defaultFormat
defaultTimeZoneId
Sets the default time zone used when creating output dates. The
default for this property is GMT.
109
Property
Description
defaultEnableFormatDateOutput
defaultMaxNestingDepth
The access controller recognizes the /rest/model/ syntax and then maps the actor and call to a controller.
110
/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
111
<actor-template default-chain-id="commitOrder"
xsi:noNamespaceSchemaLocation="http://www.atg.com/xsds/ActorChain.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<actor-chain id="commitOrder" transaction="TX_SUPPORTS">
<form id="commitOrderFormHandler"
name="/atg/commerce/custsvc/order/CommitOrderFormHandler"
handle="commitOrder" var="commitOrderFormHandler">
<input name="allowEmptyOrders" value="${param.allowEmptyOrders}"/>
<input name="salesChannel" value="${param.salesChannel}"/>
<input name="siteId" value="${param.siteId}"/>
<input name="commitOrderErrorURL"
value="/model/atg/commerce/custsvc/order/
CommitOrderActor/commitOrder-error"/>
<input name="commitOrderSuccessURL"
value="/model/atg/commerce/custsvc/order/
CommitOrderActor/commitOrder-success"/>
</form>
</actor-chain>
<actor-chain id="commitOrder-success" transaction="TX_SUPPORTS">
<actor id="success" name="/atg/commerce/custsvc/order/
OrderConfirmationActor" chain-id="orderConfirmation"
return-model-var="model">
<output id="model" add-map-children="true" value="${model}"/>
<actor>
</actor-chain>
<actor-chain id="commitOrder-error" transaction="TX_SUPPORTS">
<component id="fh" name="/atg/commerce/custsvc/order/
CommitOrderFormHandler" filter-id="full"/>
<output id="concurrentUpdate" name="concurrentUpdate"
value="${fh.concurrentUpdate}"/>
<output id="order" name="order" value="${fh.concurrentUpdate ?
fh.order : null}" filter-id="full"/>
</actor-chain>
</actor-template>
When creating a form handler, it is best to define success and error chains in the base directory, such as /DCS,
and then XML combine the success chain in your Web application directory.
Note that when you are creating an actor-chain component in development mode, it is best to disable the
Dynamo session confirmation number. To do this, disable the enforceSessionConfirmation parameter in
your local /atg/dynamo/service
/actor/Configuration.properties file. Once you have finished testing the component, you can set the
property back to use session confirmation. Refer to the Using Dynamo Session Confirmation Numbers (page
70) section for further information.
3. If required, create a success chain using XML combination in the Web application directory.
For example, the following example displays an order confirmation after the order has been committed.
<actor-template default-chain-id="commitOrder">
<actor-chain id="comittOrder-error" transaction="TX_SUPPORTS">
</actor-chain>
<actor-chain id="commitOrder-success">
<actor id="success" name="/atg/commerce/custsvc/order/
OrderConfirmationActor" chain-id="orderConfirmation"
112
return-model-var="model"/>
<output id="model" add-map-children="true" value="${model}"/>
</actor>
</actor-chain>
</actor-template>
4. Register the actor-chains in the ActorChainRestRegistry so that they are enabled for REST access.
By default, no actors are registered. Actor-chains accessed from REST or from success and error URLs must be
registered in the application module. Actor-chains that are accessed only from nested actors do not need to
be registered. Note that each chain ID should be registered separately. For information on registering actors,
refer to the Enabling REST Services (page 69) section.
# /atg/rest/registry/ActorChainRestRegistry.properties
registeredUrls+=\
/atg/commerce/custsvc/order/CommitOrderActor/commitOrder, \
/atg/commerce/cstsvc/order/CommitOrderActor/
commitOrder-success, \
/atg/commerce/custsvc/order/CommitOrderActor/
commitOrder-error
Note that you can enable debugging when creating your filter by setting the loggingDebug attribute to
true in the /atg/dynamo/service/filter/
113
During your development and testing, you may want to disable the Dynamo session confirmation numbers,
as discussed in the Using Dynamo Session Confirmation Numbers (page 70) section. To disable the session
confirmation numbers, set the enforceSessionConfirmation parameter in your local /atg/dynamo/
service
/actor/Configuration.properties file to false. Note that the following type of ambiguous error will
114
The following REST MVC services have been made available so that you can begin issuing them immediately
upon installation of your REST configuration.
As described in previous sections, REST MVC calls are based on actors that perform specific functions. This
section is organized by tasks that each actor performs for external-facing customers. For REST MVC calls for
agents, refer to the Internal REST MVC Service Call Examples (page 177) section.
Note that this section contains information on desktop REST MVC calls. For information on REST calls used by
mobile applications, refer to the Commerce Reference Store IUA Overview document.
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.
115
Note: The following examples are provided as guidelines for working with External REST MVC calls. The
responses returned by your server may vary based upon your environments configuration.
116
Actor-Chain
Description
login
logout
create
update
detailed
summary
creditCards
currentCatalog
addresses
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
password
117
Parameters: None
118
Parameter
Description
autoLogin
realmId
firstName
middleName
lastName
password
confirmPassword
login
dateOfBirth
gender
homeAddress.address1
homeAddress.address2
homeAddress.address3
homeAddress.city
homeAddress.state
homeAddress.postalCode
homeAddress.country
Parameter
Description
homeAddress.phoneNumber
homeAddress.companyName
homeAddress.county
homeAddress.jobTitle
homeAddress.faxNumber
homeAddress.prefix
A prefix used when creating the home address, for example, Mr. or Dr.
homeAddress.suffix
A suffix used when creating the user name associated with the home
address, for example, Jr.
homeAddress.firstName
The first name of the customer associated with the home address.
homeAddress.middleName
homeAddress.lastName
The last name of the customer associated with the home address.
daytimeTelephoneNumber
Parameter
Description
autoLogin
119
120
Parameter
Description
realmId
firstName
middleName
lastName
password
confirmPassword
login
dateOfBirth
gender
homeAddress.address1
homeAddress.address2
homeAddress.address3
homeAddress.city
homeAddress.state
homeAddress.postalCode
homeAddress.country
homeAddress.phoneNumber
homeAddress.companyName
homeAddress.county
homeAddress.jobTitle
homeAddress.faxNumber
homeAddress.prefix
A prefix associated with the customer when creating the home address,
for example, Mr. or Dr.
homeAddress.suffix
A suffix to display for the customer when displaying the home address,
for example, Jr.
homeAddress.firstName
The first name of the customer associated with the home address.
Parameter
Description
homeAddress.middleName
homeAddress.lastName
The last name of the customer associated with the home address.
daytimeTelephoneNumber
121
{"order": {
"lastModifiedTime": 1363293103777,
"shippingGroupCount": 1,
"paymentGroupCount": 1,
"shippingGroups": [{
"specialInstructions": {},
"handlingInstructions": [],
"state": 0,
"locationId": null,
"shippingMethod": "Ground",
"id": "sg140009",
"trackingNumber": null,
"priceInfo": null,
"description": "sg140009",
"actualShipDate": null,
"submittedDate": null,
"shipOnDate": null,
"shippingAddress": {
"middleName": null,
"lastName": "Smith",
"ownerId": null,
"state": "MA",
"address1": "1 Main Street",
"address2": null,
"address3": null,
"companyName": null,
"suffix": null,
"city": "Cambridge",
"country": "USA",
"id": null,
"postalCode": "02046",
"faxNumber": null,
"phoneNumber": "6176378687",
"county": null,
"email": "jsmith@example.com",
"prefix": null,
"firstName": "John",
"jobTitle": null
},
"stateDetail": null
}],
"commerceItems": [{
"id": "ci11000002",
"productDisplayName": "Roseanna Storage Ottoman",
"returnedQuantity": 0,
"priceInfo": {
"amount": 159.2,
"quantityDiscounted": 1,
"discountable": true,
"priceListId": "listPrices",
"onSale": false,
"rawTotalPrice": 199,
"currencyCode": "USD",
"amountIsFinal": false,
"listPrice": 199,
"discounted": true,
"currentPriceDetailsSorted": [{
122
"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",
123
"faxNumber": null,
"phoneNumber": "6176378687",
"county": null,
"email": "jsmith@example.com",
"prefix": null,
"firstName": "John",
"jobTitle": null
},
"creditCardType": "Visa",
"orderId": null
}],
"profileId": "230000",
"creationTime": 1363291121877,
"relationships": [{
"id": "r110006",
"amount": 0,
"relationshipType": "SHIPPINGQUANTITY",
"returnedQuantity": 0,
"shippingGroupId": "sg140009",
"commerceItemId": "ci11000002",
"quantity": 1
}],
"totalCommerceItemCount": 1
}}
124
Actor-Chain
Description
addItemToOrder
addMultipleItemsToOrder
moveToPurchaseInfo
moveToPurchaseInfoByCommerceId
moveToPurchaseInfoByRelId
removeAndAddItemToOrder
Actor-Chain
Description
removeItemFromOrder
Removes an item from the shopping cart using the SKU ID.
removeItemFromOrderByRelationshipId
setOrder
setOrderByCommerceId
setOrderByRelationshipID
Parameter
Description
addItemCount
The number of items being added to the shopping cart. This is different than the
quantity of each product being added.
catalogRefId
giftlistId
Used only when adding gift or wishlist items to the shopping cart. Identifies the ID of
the list.
giftlistItemId
Used only when adding gift or wishlist items to the shopping cart. Identifies the ID of
the list item.
locationId
Used only for in-store pickup. This identifies the location of the store.
productId
quantity
The number of each product being added to the shopping cart. For example, two
sweaters or four pairs of shoes.
125
addMultipleItemsToOrder"
Parameter
Description
addToWishlist
Boolean parameter used only for adding wish list items to the shopping cart.
catalogRefIds
giftlistId
Used only when adding gift or wishlist items to the shopping cart. Identifies the gift
list ID.
giftlistItemId
Used only when adding gift or wishlist items to the shopping cart. Identifies the ID of
the list item.
locationId
Used only for in-store pickup, identifies the location of the store.
productId
quantity
The number of each product being added to the shopping cart. For example, two
sweaters or four pairs of shoes.
126
127
Parameter
Description
catalogRefIds
productId
quantity
removalCommerceIds
128
Parameters: None
Actor-Chain
Description
getShippingGroups
specifyDefaultShippingGroup
applyDefaultShippingGroup
getAllCommerceItemShippingInfos
applyShippingGroups
splitShippingInfos
129
Parameter
Description
createOneInfoPerUnit
init
shippingGroupTypes
130
"commerceItemId": "ci11000002"
}]}
}
Parameter
Description
defaultShippingGroupName
131
Parameter
Description
cisicount
cisiList.shippingGroupName
cisiList.shippingMethod
Parameter
Description
cisiList.quantity
cisiList.splitQuantity
cisiList.shipppingGroupName
cisiList.splitShippingGroupName
132
Parameter
Description
hardgoodShippingGroupName
hardgoodShippingGroupType
firstName
The first name of the customer associated with this shipping group.
middleName
lastName
The last name of the customer associated with this shipping group.
address1
address2
city
state
133
Parameter
Description
country
postalCode
The postal code of the address associated with this shipping group.
phoneNumber
134
Parameter
Description
nickname
firstName
The first name of the customer associated with this shipping group.
middleName
The middle name or initial of the customer associated with this shipping group.
lastName
The last name of the customer associated with this shipping group.
address1
The first address field of the address associated with this shipping group.
address2
The second address field of the address associated with this shipping group.
city
state
country
postalCode
The postal code of the address associated with this shipping group.
phoneNumber
The phone number of the customer associated with this shipping group.
Actor-Chain
Description
getPaymentGroups
specifyDefaultPaymentGroup
applyDefaultPaymentGroup
getCommerceIdentifierPaymentInfos
applyMultiplePaymentGroups
Parameter
Description
init
This Boolean parameter, if true, will clear payment group information and
the Commerce Identifier Payment Info (CIPI) , and initialize payment groups
and the Commerce Item Shipping Info (CISI).
createAllPaymentInfos
This parameter will look for all Commerce Identifier Payment Info (CIPI), and
returns information from all payment groups.
paymentGroupTypes
135
{"paymentGroups": {"Visa": {
"amount": 109.2,
"currencyCode": "USD",
"expirationMonth": "1",
"expirationYear": "2014",
"paymentId": "pg140002",
"creditCardNumber": "1111",
"expirationDayOfMonth": null,
"billingAddress": {
"lastName": "Smith",
"postalCode": "02046",
"phoneNumber": "6176378687",
"email": "jsmith@example.com",
"state": "MA",
"address1": "1 Main St",
"address2": "",
"firstName": "John",
"city": "Cambridge",
"country": "USA"
},
"creditCardType": "Visa",
"orderId": null
}}}
Parameter
Description
defaultPaymentGroupName
136
Parameter
Description
listId
137
138
"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,
139
"listPrice": 5,
"amountIsFinal": false,
"discounted": false,
"salePrice": 0
},
"state": 0,
"quantity": 1,
"catalogRefId": "xsku1043"
}],
"totalCommerceItemCount": 1
},
"paymentMethod": "visa - 1111",
"amountType": "ORDERAMOUNT"
}
]}
Parameter
Description
listId
cipicount
cipiList.amount
cipiList.creditCardVerificationNumber
140
Parameter
Description
creditCardType
creditCardNumber
expirationMonth
expirationYear
generateNickname
Used to generate a nickname for the credit card. This parameter is always set
to true.
firstName
middleName
lastName
address1
address2
city
state
country
postalCode
phoneNumber
141
Parameter
Description
nickname
creditCardType
creditCardNumber
expirationMonth
expirationYear
firstName
middleName
lastName
address1
address2
city
state
country
postalCode
phoneNumber
142
Actor-Chain
Description
getCurrentCatalogRootCategories
getCategory
getProduct
{"rootCategories": [
{
"id": "rootCategory",
"description": null,
"defaultParentCategory": null,
"displayName": "Commerce Root",
"type": null
},
{
"id": "NonNavigableProducts",
"description": "",
"defaultParentCategory": null,
"displayName": "Non Navigable Products",
"type": null
}
]}
143
Parameter
Description
categoryId
filterBySite
filterByCatalog
{
"childCategories": [
{
"id": "cat50056",
"description": null,
"defaultParentCategory": null,
"displayName": "Gift Shop",
"type": null
},
{
"id": "cat50001",
"description": "",
"defaultParentCategory": null,
"displayName": "Women",
"type": null
},
{
"id": "catMen",
"description": "",
"defaultParentCategory": null,
"displayName": "Men",
"type": null
},
{
"id": "cat50097",
"description": "",
"defaultParentCategory": null,
"displayName": "Shoes",
"type": null
},
{
"id": "cat10016",
"description": null,
"defaultParentCategory": null,
"displayName": "Home Accents",
"type": null
}
],
144
"category": {
"id": "rootCategory",
"description": null,
"defaultParentCategory": null,
"displayName": "Commerce Root",
"type": null
}
}
Parameter
Description
productId
catalogs
filterBySite
filterByCatalog
sites
{
"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"
}],
145
"repositoryId": "xprod2085",
"highestListPrice": 19,
"description": "Tumbler glass great for mixed drinks and other beverages",
"largeImageUrl": "/crsdocroot/content/images/products/large/
HOME_TumblerGlass_large.jpg",
"longDescription": "Our heavy glass tumblers are a versatile addition to your barware
collection. Holds 12 ounces. Dishwasher safe. Made in Poland.",
"isNavigableProduct": true,
"mediumImageUrl": "/crsdocroot/content/images/products/medium/
HOME_TumblerGlass_medium.jpg",
"displayName": "Tumbler Glass",
"thumbnailImageUrl": "/crsdocroot/content/images/products/thumb/
HOME_TumblerGlass_thumb.jpg"
}}
Searching a Catalog
The catalog search REST MVC call uses Endeca catalog search. For information on Endeca catalog searches, refer
to the Platform Installation and Configuration Guide.
To initiate a catalog search call:
Actor-Chain
Description
productPriceRanges
Provides the lowest and highest sale price for a product. These
prices are obtained from the users profile.
skuPrices
146
Parameter
Description
productId
Parameter
Description
productId
skuId
147
Parameter
Description
orderId
{"result": {
"id": "o120001",
"priceInfo": {
"amount": 109.2,
"total": 109.2,
"shipping": 0,
"currencyCode": "USD",
"tax": 0,
"rawSubtotal": 119.2,
"discountAmount": 10
},
"commerceItems": [{
"id": "ci11000001",
"productDisplayName": "Hubbard Chair",
"priceInfo": {
"amount": 119.2,
"currencyCode": "USD",
"currentPriceDetailsSorted": [{
"amount": 119.2,
"currencyCode": "USD",
"quantity": 1,
"detailedUnitPrice": 119.2
}]
},
"quantity": 1,
"catalogRefId": "xsku2126",
"productId": "xprod2126"
}],
"totalCommerceItemCount": 1
}}
148
Actor-Chain
Description
cancelCurrentOrder
cancelOrder
Parameter
Description
orderIdToCancel
Saving an Order
The SaveOrderActor saves an order. It is located in: /atg/commerce/order/purchase/
SaveOrderActor.
This actor has the saveOrder actor-chain:
149
Parameter
Description
description
Claiming a Coupon
The CouponActor is used to claim a coupon. It is located in: /atg/commerce/promotion/CouponActor.
This actor has the claimCoupon actor-chain:
Parameter
Description
couponClaimCode
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.
150
"shippingGroups": [{
"specialInstructions": {},
"handlingInstructions": [],
"state": 0,
"locationId": null,
"shippingMethod": "Ground",
"id": "sg140002",
"trackingNumber": null,
"priceInfo": {
"amount": 6.5,
"currencyCode": "USD",
"amountIsFinal": false,
"discounted": false,
"rawShipping": 6.5
},
"description": "sg140002",
"actualShipDate": null,
"submittedDate": null,
"shipOnDate": null,
"shippingAddress": {
"middleName": null,
"lastName": "Smith",
"ownerId": null,
"state": "MA",
"address1": "1 Main St",
"address2": "",
"address3": null,
"companyName": null,
"suffix": null,
"city": "Cambridge",
"country": "USA",
"id": null,
"postalCode": "02046",
"faxNumber": null,
"phoneNumber": "6176378687",
"county": null,
"email": "jsmith@example.com",
"prefix": null,
"firstName": "John",
"jobTitle": null
},
"stateDetail": null
}],
"commerceItems": [{
"id": "ci11000001",
"productDisplayName": "Hubbard Chair",
"returnedQuantity": 0,
"priceInfo": {
"amount": 119.2,
"quantityDiscounted": 1,
"discountable": true,
"priceListId": "listPrices",
"onSale": false,
"rawTotalPrice": 149,
"currencyCode": "USD",
"amountIsFinal": false,
"listPrice": 149,
"discounted": true,
"currentPriceDetailsSorted": [{
"amount": 119.2,
151
"itemPriceInfo": null,
"currencyCode": "USD",
"tax": 0,
"range": {
"lowBound": 0,
"class": "atg.core.util.Range",
"highBound": 0,
"size": 1
},
"amountIsFinal": false,
"discounted": true,
"quantity": 1,
"detailedUnitPrice": 119.2
}],
"salePrice": 0
},
"catalogId": null,
"quantity": 1,
"catalogRefId": "xsku2126",
"catalogKey": "en_US",
"productId": "xprod2126"
}],
"id": "o120001",
"siteId": "homeSite",
"taxPriceInfo": {
"amount": 0,
"currencyCode": "USD",
"countyTax": 0,
"amountIsFinal": false,
"countryTax": 0,
"discounted": false,
"stateTax": 0,
"cityTax": 0,
"districtTax": 0
},
"priceInfo": {
"amount": 109.2,
"total": 115.7,
"shipping": 6.5,
"currencyCode": "USD",
"tax": 0,
"amountIsFinal": false,
"discounted": true,
"manualAdjustmentTotal": 0,
"rawSubtotal": 119.2,
"discountAmount": 10
},
"paymentGroups": [{
"amount": 0,
"currencyCode": null,
"expirationMonth": "1",
"expirationYear": "2014",
"paymentId": "pg140002",
"creditCardNumber": "1111",
"expirationDayOfMonth": null,
"billingAddress": {
"middleName": null,
"lastName": "Smith",
"ownerId": null,
"state": "MA",
152
Committing an Order
The CommitOrderActor is used to commit the order. The path to this actor is: /atg/commerce/order/
purchase/CommitOrderActor.
This actor contains the commitOrder actor-chain.
Parameter
Description
allowEmptyOrders
153
Parameter
Description
salesChannel
The sales channel used to submit the order. The values are Web, Call
Center or Scheduled Orders, and are defined in the Order repository.
siteId
154
getClosenessQualifiers"
Actor-Chain
Description
createReturn
selectItems
returnReasons
confirmReturn
confirmation
cancelReturnRequest
applyRefunds
modifiableRefundsMethodList
isCurrentOrderReturnable
isReturnActive
returnsHistory
returns
nonReturnItemDetails
Initiating a Return
The createReturn actor-chain initiates and creates a return request. Note that this actor-chain calls
the ReturnFormHandler, as opposed to the internal createReturn actor-chain, which calls the
155
refer to the Creating a Return (page 293) section. This actor-chain contains the following parameter:
Parameter
Description
newOrderId
Parameter
Description
processName
jsonReturnRequest
156
157
"catalogRefId":"xsku2519_2",
"suggestedRefundAmount":50.52,
"disposition":null,
"returnReason":"didNotLike"
},
{
"quantityToExchange":0,
"suggestedTaxRefundShare":0,
"quantityReceived":0,
"itemCurrencyCode":"USD",
"returnItemId":"xcr10102",
"actualTaxRefundShare":0,
"refundAmount":51.44,
"shippingGroupId":"xcsg20080",
"quantityReturned":0,
"quantityShipped":1,
"quantityAvailable":1,
"description":"Corduroy Cargo Pants",
"quantityToReturn":1,
"actualShippingRefundShare":6.31,
"suggestedShippingRefundShare":6.31,
"commerceItemId":"xci1000052",
"catalogRefId":"xsku2512_2",
"suggestedRefundAmount":51.44,
"disposition":null,
"returnReason":"defective"
}
],
"processImmediately":false,
"rma":null,
"returnFee":0,
"orderId":"xco30045",
"profile":{
"middleName":null,
"lastName":"Smith",
"id":"se-570085",
"login":"jsmith@example.com",
"firstName":"Joe"
}
}
}
158
{
"reasons": {
"incorrectSize": "Incorrect Size",
"incorrectColor": "Incorrect Color",
"didNotMeetExpectations": "Did Not Meet Expectations",
"didNotLike": "Did Not Like",
"defective": "Defective",
"incorrectItem": "IncorrectItem"
}
}
Confirming a Return
The confirmReturn actor-chain submits and processes a return request, and displays confirmation detail if a
submission is successful.
Parameters: None
Canceling a Return
The cancelReturnRequest actor-chain cancels the return request at any point during the returns process.
Parameters: None
159
{
"modifiableRefundMethodList": [{
"refundType": "creditCard",
"amount": 51.31
}]
}
Parameter
Description
returnMethodListSize
The array size to retrieve from the JSP. The array size corresponds to the
number of refund methods available.
160
Parameter
Description
orderId
Parameter
Description
orderId
161
162
Parameter
Description
creditCardType
creditCardNumber
expirationMonth
expirationYear
firstName
Parameter
Description
middleName
lastName
address1
address2
city
state
country
postalCode
phoneNumber
{"promotionsLost":"promo50012"}
163
Actor-Chain
Description
createGiftlist
updateGiftlist
addItemToGiflList
removeItemFromGiftlist
addItemToWishlist
removeItemFromWishlist
moveItemsFromCart
deleteGiftlist
profileGiftlists
164
Parameter
Description
isPublished
eventName
eventDate
eventType
description
comments
shippingAddressId
Parameter
Description
instructions
Parameter
Description
giftlistId
isPublished
eventName
eventDate
eventType
description
shippingAddressId
instructions
165
Parameter
Description
giftlistId
quantity
productId
catalogRefIds
The catalog reference ID of the product being added to the gift list.
Parameter
Description
quantity
productId
catalogRefIds
The catalog reference ID of the product being added to the wish list.
166
Parameter
Description
giftlistId
The ID of the gift list from which the items will be removed.
Parameter
Description
removeGiftitemIds
Parameter
Description
removeGiftitemIds
Parameter
Description
giftlistId
The ID of the gift or wish list to which the items will be moved.
itemIds
quantity
167
The following example shows how you would specify the quantity for a particular item within the cart:
Parameter
Description
giftlistId
{"giftlists": [
{
"name": "Birthday",
"repositoryId": "xgl20004"
168
},
{
"name": "Anniversary",
"repositoryId": "gl430003"
}
]}
Parameter
Description
giftlistId
{"giftlist": {
"giftlistItems": [],
"instructions": "",
"description": "Upcoming birthday gifts.",
"name": "Birthday",
"public": true,
"date": {"time": 1386521853000},
"type": "Birthday",
"repositoryId": "xgl20004",
"addressId": "se-980030"
}
Parameter
Description
giftlistId
169
170
{
"repositoryId":"xgi10008",
"productId":"xprod2138",
"siteId":"homeSite",
"skuId":"xsku2138",
"quantity":1
}
]}
{"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
},
{
171
"repositoryId":"xgi10005",
"productId":"xprod2032",
"siteId":"storeSiteUS",
"skuId":"xsku2032",
"quantity":1
},
{
"repositoryId":"xgi10006",
"productId":"xprod2071",
"siteId":"homeSite",
"skuId":"xsku2071",
"quantity":1
},
{
"repositoryId":"xgi10007",
"productId":"xprod2116",
"siteId":"homeSite",
"skuId":"xsku2116",
"quantity":1
},
{
"repositoryId":"xgi10008",
"productId":"xprod2138",
"siteId":"homeSite",
"skuId":"xsku2138",
"quantity":1
}
]}
172
Parameter
Description
currentPage
searchInput
firstName
lastName
eventType
eventDate
resultsPerPage
state
{"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
}
]}
173
Actor-Chain
Description
locateItems
currentResultPageNum
Parameter
Description
skuId
countryCode
state
city
postalCode
distance
maxResultsPerPage
174
"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"
}
}
Parameter
Description
pageNum
Identifies which page of the results set is being viewed. The default value
is 1, with the base value of this parameter set to1 instead of 0 for usability.
maxResultsPerPage
Identifying a State
The StateListActor is used to identify the state of a users profile locale. The path of this actor is /atg/
commerce/util, and it contains the states actor-chain.
Parameter
Description
countryCode
175
176
The following REST MVC services enable Call Center agents to assist customers. The following REST MVC calls
examples are specific to internal users, such as those used by Oracle Commerce Service Center, and are intended
for the creation of REST MVC calls for Commerce Service Center Call Center agent actions.
As described in previous sections, REST MVC calls are based on actors that perform specific functions. This
section is organized by tasks that agents perform on behalf of customers. These agent-specific REST MVC calls
are different than external user REST MVC calls in that they use the agent_cookies.txt file to store cookie
information, and are located in the DCS-CSR modules. For REST MVC calls for external customers, refer to the
External REST MVC Service Call Examples (page 115) section.
177
This example begins with the agent logging in to the REST server, and ends when the customer is sent an order
confirmation e-mail.
Note: The following examples are provided as guidelines for working with Internal REST MVC calls. The
responses returned by your server may vary based upon your environments configuration.
{"sessionConfirmationNumber":-5166444348429687167}
178
Actor-Chain
Description
login
logout
Logging In Agents
The login actor-chain is used to log the agent into the site and verify the appropriate login and password
credentials.
Parameter
Description
login
password
If the log in information proves to be correct, the following success server response occurs:
{"userId": "svcUserAdmin>}
If the log in information proved to be incorrect, the following exception would occur:
{"formError": true, "formExceptions":[{"localizedMessage":"The password and login
combination is incorrect.","errorCode":"invalidPassword"}]}
179
Parameter
Description
TryLogout
Parameter
Description
newPassword
oldPassword
confirmPassword
180
Parameter
Description
agentUserDefaultHomeTab
Restoring Defaults
You can restore the defaults for agent preferences using the RestoreDefaultAgentOptionsActor,
which uses the restoreDefaults actor-chain. The actor is located at /atg/svc/ui/formhandlers/
RestoreDefaultAgentOptionsActor.
Parameters: None
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:
181
Parameter
Description
doWarnings
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
{
"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.
Ending a Call
The /atg/svc/agent/ui/formhandlers/EndCallActor contains the endCall actor-chain, which is used to
end a call in Commerce Service Center:
182
Parameter
Description
doWarnings
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
{
"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.
183
Parameter
Description
noteText
share
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
184
Actor-Chain
Description
workTicket
createNewTicket
saveTicket
associateTicket
Associates a ticket.
escalateTicket
Escalates a ticket.
closeTicket
Closes a ticket.
releaseTicket
deferTicket
Actor-Chain
Description
reassignTicket
sendToGroup
closeAsDuplicate
beginEdit
endEdit
viewActiveTicket
Parameter
Description
ticketId
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
subStatus
185
Parameter
Description
dispositionOption
reasonCode
ticketNote
subStatus
publicNote
doDispositionPrompt
Saving a Ticket
The saveTicket actor-chain allows an agent to save a ticket.
Parameter
Description
ticketId
Associating a Ticket
The associateTicket actor-chain allows an agent to associate a ticket.
186
Parameter
Description
ticketId
associatedTicketId
Parameter
Description
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
subStatus
Escalating a Ticket
The escalateTicket actor-chain allows an agent to escalate a ticket.
Parameter
Description
ticketId
escalationLevel
group
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
subStatus
187
Closing a Ticket
The closeTicket actor-chain allows an agent to close a ticket.
Parameter
Description
ticketId
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
subStatus
Releasing a Ticket
The releaseTicket actor-chain allows an agent to release a ticket.
188
Parameter
Description
ticketId
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
Parameter
Description
publicNote
subStatus
Deferring a Ticket
The deferTicket actor-chain allows an agent to defer a ticket.
Parameter
Description
ticketId
date
retain
share
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
subStatus
189
Reassigning a Ticket
The reassignTicket actor-chain allows an agent to reassign a ticket.
Parameter
Description
ticketId
doTicketDispositionPrompt
reassignAgent
dispositionOption
reasonCode
ticketNote
publicNote
subStatus
190
Parameter
Description
ticketId
group
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
Parameter
Description
publicNote
subStatus
Parameter
Description
ticketId
duplicateTicketId
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
subStatus
Editing a Ticket
The beginEdit actor-chain allows an agent to begin editing a ticket.
191
Parameter
Description
ticketId
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
subStatus
192
Parameter
Description
ticketId
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
subStatus
parameterMap.priority
parameterMap.ticketQueue
parameterMap.customerDetails_firstName
Parameter
Description
parameterMap.customerDetails_lastName
parameterMap.customerDetails_phone
parameterMap.customerDetails_email
parameterMap.customerDetails_address
parameterMap.customerDetails_city
parameterMap.customerDetails_state
parameterMap.customerDetails_country
parameterMap.customerDetails_postalCode
Parameter
Description
sortDirection
sortField
193
Parameter
Description
currentPage
resultsPerPage
Looking Up a Ticket
The TicketLookupActor allows an agent to look up a ticket. This service calls the TicketLookupDroplet to
provide search parameters. The TicketLookupActor is located at /atg/ticketing/droplet/.
This actor uses the lookup actor-chain.
Parameter
Description
searchProperty
The name of the ticketing property to search on when performing the lookup.
value
includes
ticketId
startIndex
The first ticket to return. This property is used to break large query results into
smaller pieces.
numTickets
This example looks for a specific ticket, which is identified by its ticket ID.
194
195
"textContent": null,
"reason": null,
"inProgress": null,
"type": "agentAssignment",
"id": "1600009",
"activityData": null,
"userName": null,
"creationTime": {
"time": 1375716548000
},
"public": false,
"heading": null
},
{
"abstract": null,
"previousSubStatus": {
"subStatusName": "Closed",
"parentStatus": "Closed"
},
"application": "Agent",
"textContent": null,
"newSubStatus": {
"subStatusName": "ReOpened",
"parentStatus": "Open"
},
"reason": null,
"inProgress": null,
"type": "statusChange",
"id": "1600008",
"activityData": null,
"userName": null,
"creationTime": {
"time": 1375716548000
},
"public": false,
"heading": null
},
{
"abstract": null,
"previousSubStatus": {
"subStatusName": "ReOpened",
"parentStatus": "Open"
},
"application": "Agent",
"textContent": null,
"newSubStatus": {
"subStatusName": "Closed",
"parentStatus": "Closed"
},
"reason": null,
"inProgress": null,
"type": "statusChange",
"id": "1600010",
"activityData": null,
"userName": null,
"creationTime": {
"time": 1375716548000
},
"public": false,
"heading": null
196
},
{
"abstract": null,
"previousSubStatus": {
"subStatusName": "Open",
"parentStatus": "Open"
},
"application": "Agent",
"textContent": null,
"newSubStatus": {
"subStatusName": "Closed",
"parentStatus": "Closed"
},
"reason": null,
"inProgress": null,
"type": "statusChange",
"id": "1600005",
"activityData": null,
"userName": null,
"creationTime": {
"time": 1375716201000
},
"public": false,
"heading": null
},
{
"abstract": null,
"application": "Agent",
"textContent": null,
"reason": null,
"inProgress": null,
"type": "agentAssignment",
"id": "999999",
"activityData": null,
"userName": null,
"creationTime": {
"time": 1375276229000
},
"public": false,
"heading": null
}],
"id": "2200",
"duplicateOfTicketId": null,
"loadedTimestamp": null,
"slaBaseTimestamp": {
"time": 1374054964000
},
"description": null,
"priority": 0,
"lastModifiedInDays": 0,
"customerDetails": null,
"creationTime": {
"time": 1374054650000
},
"application": "Agent",
"lastModified": {
"time": 1376639939000
},
"originatingTicketId": null,
"ageInDays": 30,
197
"mergeable": true,
"externalReferences": [],
"inProgressActivity": null,
"loaded": false,
"externalTicketId": null,
"inboundChannelAddress": null,
"subStatus": {
"subStatusName": "Open",
"parentStatus": "Open"
},
"pushable": false,
"due": null,
"releaseTime": null,
"defaultOutboundChannel": "unknown",
"user": null,
"displayId": "2200",
"ticketQueue": null
}
}
198
Parameter
Description
currentPage
resultsPerPage
sortDirection
sortField
parameterMap.id
parameterMap.subStatus_subStatusName
parameterMap.ticketQueue_id
parameterMap.escalationLevel
parameterMap.customerDetails_firstName
parameterMap.customerDetails_lastName
Parameter
Description
parameterMap.customerDetails_phone
parameterMap.customerDetails_email
parameterMap.description
parameterMap.owningAgentId
parameterMap.dates_byCreatedDate
parameterMap.dates_pastOrFromTo
parameterMap.dates_past
parameterMap.dates_past2
parameterMap.dates_fromDate
parameterMap.dates_toDate
parameterMap.dates_pastOrFromTo2
parameterMap.dates_byLastModified
parameterMap.dates_modifiedFrom
parameterMap.dates_modifiedTo
199
Parameter
Description
descriptionId
baseName
elementName
Viewing a Customer
The /atg/svc/agent/ui/formhandlers/ServiceUIProfileActor contains the viewCustomer actorchain:
Parameter
Description
customerId
200
Actor-Chain
Description
create
update
addNote
Parameter
Description
firstName
middleName
lastName
login
password
dateOfBirth
orderId
Used when creating an account. Indicates the order ID. If this property is set,
and saveCreditCards is set to true, copies the credit card information from
the order to the users profile. Used with Commerce Service Center only.
saveCreditCards
Used when creating an account. Indicates if the credit card information for the
customer should be saved. Used with Commerce Service Center only.
address.address1
201
Parameter
Description
address.address2
address.city
address.companyName
address.country
address.county
address.jobTitle
address.postalCode
address.faxNumber
address.firstName
address.middleName
The middle name or initial of the customer associated with the address.
address.lastName
address.phoneNumber
address.prefix
address.state
address.suffix
202
Parameter
Description
firstName
middleName
lastName
dateOfBirth
address.address1
address.address2
address.city
address.companyName
address.country
address.county
address.jobTitle
address.postalCode
address.faxNumber
address.firstName
address.middleName
The middle name or initial of the customer associated with the address.
address.lastName
address.phoneNumber
address.prefix
address.state
address.suffix
203
Parameter
Description
comment
Actor-Chain
Description
search
clearForm
The search actor-chain is used to search for customer profiles. It identifies the way that the results will display,
including the paging and sort order.
204
Parameter
Description
fieldCount
pageSize
pageNum
The page number within the pages of results This parameter is zero-based, with
the default set to 0.
maxResults
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
fields[].op
field[].value
{
"searchResponse": {"items": [
{
"lastName": "Taylor",
"postalCode": "89501",
"phoneNumber": "2125558105",
"email": "chuck@example.com",
"profileId": "se-570105",
"login": "chuck@example.com",
"firstName": "Chuck"
},
205
{
"lastName": "Thomas",
"postalCode": "59101",
"phoneNumber": "2125558855",
"email": "juan@example.com",
"profileId": "se-570056",
"login": "juan@example.com",
"firstName": "Juan"
}
]},
"pagesAvailable": 2
}
206
Parameter
Description
customerId
doWarnings
doTicketDispositionPrompt
dispositionOption
reasonCode
Parameter
Description
ticketNote
publicNote
{
"isDiscardable": false,
"allWarnings": [],
"activeTicketDisposition": true
}
Actor-Chain
Description
addAddress
updateAddress
207
Actor-Chain
Description
deleteAddress
Parameter
Description
firstName
middleName
The middle name or initial of the customer associated with this address.
lastName
address1
address2
city
state
postalCode
country
phoneNumber
setBillingAddress
Boolean value that sets the address as the default billing address.
setShippingAddress
Boolean value that sets the address as the default shipping address
{"addressId" : "270015"}
208
Parameter
Description
addressId
firstName
middleName
The middle name or initial of the customer associated with this address.
lastName
address1
address2
city
state
postalCode
country
phoneNumber
setBillingAddress
Boolean value that sets the address as the default billing address.
setShippingAddress
Boolean value that sets the address as the default shipping address.
209
Parameter
Description
addressId
Actor-Chain
Description
addCreditCard
updateCreditCard
deleteCreditCard
210
Parameter
Description
creditCardType
creditCardNumber
expirationMonth
expirationYear
billingAddressRepositoryId
firstName
Parameter
Description
middleName
lastName
address1
address2
city
state
postalCode
country
phoneNumber
setBillingAddress
setShippingAddress
defaultCreditCardSetDefault
211
Parameter
Description
createNewAddress
creditCardId
creditCardType
creditCardNumber
expirationMonth
expirationYear
billingAddressRepositoryId
firstName
middleName
lastName
address1
address2
city
state
postalCode
country
phoneNumber
setBillingAddress
setShippingAddress
defaultCreditCardSetDefault
212
\"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"
Parameter
Description
creditCardId
213
detailed"
214
"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",
215
"amount": 0,
"relationshipType": "SHIPPINGQUANTITY",
"returnedQuantity": 0,
"shippingGroupId": "sg110004",
"commerceItemId": "ci10000001",
"quantity": 1
}],
"totalCommerceItemCount": 1
}}
216
Actor-Chain
Description
addMultipleItemsToOrder
addItemToOrder
setOrder
setOrderByCommerceId
setOrderByRelationshipID
removeAndAddItemToOrder
removeItemFromOrder
removeItemFromOrderByRelationshipId
moveToPurchaseInfo
moveToPurchaseInfoByCommerceId
moveToPurchaseInfoByRelId
Actor-Chain
Description
changeSKUs
Parameter
Description
addItemCount
The number of items being added to the shopping cart. This is different than
the quantity of each product being added, this is the items array size.
items.catalogRefId
items.productId
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
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.
217
Parameter
Description
catalogRefIds
productId
quantity
The number of each product being added to the shopping cart. For example, two
sweaters or four pairs of shoes.
siteId
locationId
Used only for in-store pickup, identifies the location of the store.
addToWishlist
This Boolean parameter is used only for adding wish list items to the shopping
cart.
giftlistItemId
Used only for adding gift/wish list items. Identifies the list item ID.
giftlistId
218
addItemToOrder"
Parameter
Description
removalCatalogRefIds
The optional list of catalog reference IDs (SKU ID) to remove from the
order.
Parameter
Description
removalCommerceIds
The optional list of commerce item IDs to remove from the order.
219
Parameter
Description
removalRelationshipIds
Parameter
Description
catalogRefIds
productId
quantity
removalCommerceIds
The ID given to the item, or to a list of commerce items, that should be removed
from the order.
220
Parameter
Description
removalCommerceIds
Parameter
Description
removalRelationshipIds
221
Parameters: None
222
Actor-Chain
Description
getShippingGroups
Actor-Chain
Description
applySingleShippingGroup
applyMultipleShippingGroups
applyShippingMethods
splitShippingInfos
getAllCommerceItemShippingInfos
Parameter
Description
init
223
Parameter
Description
shipToAddressNickname
Parameter
Description
cisicount
cisiList.shippingGroupName
cisiList.shippingMethod
224
Parameter
Description
cisicount
cisiList.quantity
cisiList.splitQuantity
cisiList.shipppingGroupName
cisiList.splitShippingGroupName
Parameter
Description
shippingGroupscount
shippingGroups.shippingMethod
225
226
Parameter
Description
firstName
The first name of the customer associated with this shipping group.
middleName
The middle name or initial of the customer associated with this shipping group.
lastName
The last name of the customer associated with this shipping group.
address1
Parameter
Description
address2
city
state
country
postalCode
The postal code of the address associated with this shipping group.
phoneNumber
The phone number of the customer associated with this shipping group.
Parameter
Description
nickname
firstName
The first name of the customer associated with this shipping group.
middleName
The middle name or initial of the customer associated with this shipping group.
lastName
The last name of the customer associated with this shipping group.
address1
The first address field of the address associated with this shipping group.
address2
The second address field of the address associated with this shipping group.
city
state
country
postalCode
The postal code of the address associated with this shipping group.
227
Parameter
Description
phoneNumber
The phone number of the customer associated with this shipping group.
228
Actor-Chain
Description
getPaymentGroups
getCommerceIdentifierPaymentInfos
applyMultiplePaymentGroups
claimItem
Parameter
Description
init
229
Parameter
Description
listId
230
"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"
}
]}
Parameter
Description
claimCode
231
Parameter
Description
couponClaimCode
Parameter
Description
listId
cipicount
cipiList.amount
cipiList.creditCardVerificationNumber
232
\"atg.commerce.order.purchase.CommerceIdentifierPaymentInfo\",
\"amount\" : \"5.00\", \"creditCardVerificationNumber\" : \"1234\"}]}}"
"http://localhost:8280/rest/model/atg/commerce/custsvc/order/PaymentGroupActor/
applyMultiplePaymentGroups"
Actor-Chain
Description
getExistingAddresses
newCreditCardWithExistingAddress
newCreditCardWithNewAddress
Parameter
Description
creditCardType
233
Parameter
Description
creditCardNumber
expirationMonth
expirationYear
addressIndex
234
Parameter
Description
creditCardType
creditCardNumber
expirationMonth
expirationYear
firstName
Identifies the first name of the customer associated with this billing address.
middleName
The middle name or initial of the customer associated with this billing address.
lastName
The last name of the customer associated with this billing address.
address1
address2
city
state
country
postalCode
Parameter
Description
phoneNumber
Parameter
Description
nickname
creditCardType
creditCardNumber
expirationMonth
expirationYear
firstName
middleName
lastName
address1
address2
city
state
country
postalCode
235
Parameter
Description
phoneNumber
236
Parameter
Description
doWarnings
If set to true, will present a warning to the agent when leaving the
order they are currently working on and proceeding to the new order.
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
237
"currentLocation": "unknown",
"id": "220022",
"registrationDate": {"time": 1363218368049},
"email": "jsmith@example.com",
"homeAddress": {
"middleName": null,
"lastName": "Smith",
"item-id": null,
"state": "MA",
"address1": "1 Main Street",
"address2": null,
"address3": null,
"companyName": null,
"suffix": null,
"repositoryId": "230024",
"country": "USA",
"city": "Cambridge",
"faxNumber": null,
"postalCode": "02046",
"phoneNumber": "6176378687",
"county": null,
"prefix": null,
"firstName": "John"
},
"favoriteStores": [],
"daytimeTelephoneNumber": null,
"billingAddress": null,
"login": null,
"secondaryAddresses": {},
"purchaseLists": [],
"firstName": "John",
"shippingAddress": null,
"allowPartialShipment": false,
"creditCards": {"visa - 1111": {
"id": "usercc10001",
"expirationYear": "2022",
"expirationMonth": "1",
"creditCardNumber": "1111",
"billingAddress": {
"middleName": null,
"lastName": "Smith",
"item-id": null,
"state": "MA",
"address1": "One Main Street",
"address2": null,
"address3": null,
"companyName": null,
"suffix": null,
"repositoryId": "230038",
"country": "USA",
"city": "Cambridge",
"faxNumber": null,
"postalCode": "02046",
"phoneNumber": "6176378687",
"county": null,
"prefix": null,
"firstName": "John"
},
"creditCardType": "visa"
}}
238
}}
Actor-Chain
Description
clearForm
search
Used to search for orders. It also indicates the way that the results will display,
including the paging and sort order.
The clearForm actor-chain allows you to clear the saved session search request.
Parameters: None
The search actor-chain searches for orders and configures the result display.
Parameter
Description
fieldCount
Indicates the size of the fields array, or the number of items in the field.
pageSize
pageNum
maxResults
The total number of search results to return. The default is set to 100.
docProps
Identifies the properties of the order to return in each search result. The default
is set to all.
docSort
The type of sort property to use. The default is strprop. Use numpropr if you
are doing a number property sort.
docSortOrder
docSortProp
239
Parameter
Description
saveRequest
fields[].name
fields[].op
field[].value
240
}
]},
"pagesAvailable": 7
}
Parameter
Description
viewOrderId
Parameter
Description
customerId
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
dispositionOption
reasonCode
ticketNote
241
Parameter
Description
publicNote
Parameter
Description
orderIdToCancel
242
{"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"
},
243
{
"description": "Fine crystal tumbler for highballs and other beverages",
"largeImageUrl": "/crsdocroot/content/images/products/large/
HOME_JackJillGlass_large.jpg",
"longDescription": "This sturdy, sophisticated crystal glass adds an elegant
touch. Perfect for entertaining and holiday use.",
"isNavigableProduct": null,
"mediumImageUrl": "/crsdocroot/content/images/products/medium/
HOME_JackJillGlass_medium.jpg",
"fullImageUrl": "/crsdocroot/content/images/products/full/
HOME_JackJillGlass_full.jpg",
"displayName": "Jack and Jill Glass Tumbler",
"repositoryId": "xprod2074",
"thumbnailImageUrl": "/crsdocroot/content/images/products/thumb/
HOME_JackJillGlass_thumb.jpg"
}
]
}
Actor-Chain
Description
persistOrder
commitOrder
sendConfirmationMessage
validateTemplateOrder
Validates a scheduled order template order. For information on this actorchain, refer to the Working with Scheduled Orders (page 251) section.
The commitOrder actor-chain commits an order and contains the following parameters:
244
Parameter
Description
allowEmptyOrders
salesChannel
siteId
createTemplateFromSubmittedOrder
245
"amountIsFinal": false,
"discounted": true,
"rawShipping": 0
},
"description": "sg110016",
"actualShipDate": null,
"submittedDate": null,
"shipOnDate": null,
"shippingAddress": {
"middleName": null,
"lastName": null,
"ownerId": null,
"state": null,
"address1": null,
"address2": null,
"address3": null,
"companyName": null,
"suffix": null,
"city": null,
"country": null,
"id": null,
"postalCode": null,
"faxNumber": null,
"phoneNumber": null,
"county": null,
"email": null,
"prefix": null,
"firstName": null,
"jobTitle": null
},
"stateDetail": null
}],
"commerceItems": [{
"id": "ci10000002",
"productDisplayName": "Swiss Detail Clock",
"returnedQuantity": 0,
"priceInfo": {
"amount": 99,
"quantityDiscounted": 0,
"discountable": true,
"priceListId": "listPrices",
"onSale": false,
"rawTotalPrice": 99,
"currencyCode": "USD",
"amountIsFinal": false,
"listPrice": 99,
"discounted": false,
"currentPriceDetailsSorted": [{
"amount": 99,
"itemPriceInfo": null,
"currencyCode": "USD",
"tax": 0,
"range": {
"lowBound": 0,
"class": "atg.core.util.Range",
"highBound": 0,
"size": 1
},
"amountIsFinal": false,
"discounted": false,
246
"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
}}
247
Parameters: None
Parameter
Description
orderID
Parameter
Description
orderID
248
Duplicating an Order
The DuplicateOrderActor allows you to duplicate an existing order. When you duplicate the order, you can
duplicate the ticket disposition of the order. For additional information on working with ticket dispositions, refer
to the Working with Ticket Disposition Warnings and Messages (page 311) section. This actor is located at /
atg/commerce/custsvc/order/DuplicateOrderActor.
This actor uses the duplicateOrder actor-chain, which contains the following parameters:
Parameter
Description
orderToDuplicate
doWarnings
doTicketDispositionPrompt
ticketDispositionOptions.dispositionOption
If doTicketDispositionPrompt is enabled,
this provides a ticket disposition option.
ticketDispositionOptions.reasonCode
If doTicketDispositionPrompt is selected,
this provides a ticket disposition reason code.
ticketDispositionOptions.ticketNote
If doTicketDispositionPrompt is
selected,provides a note associated with the
ticket.
ticketDispositionOptions.publicNote
If doTicketDispositionPrompt is selected,
identifies if the ticket note is public.
249
Parameter
Description
comment
Parameter
Description
comment
250
Parameter
Description
completeQuoteParameters
This identifies the map and its string keys and values that provides
quote information.
Actor-Chain
Description
createCSRScheduledOrder
updateCSRScheduledOrder
Parameter
Description
name
251
Parameter
Description
scheduleType
startDate
endDateOption
Options that can be set for the end date of the scheduled order. The
options include none, afterOccurrences or endBy.
numberOfOccurances
endDate
The end date of the scheduled order. Used with the endBy parameter.
daysOption
This calendar property sets the delivery days of the scheduled order.
The options for this property are allDays, selectedDays and
selectedDates.
selectedDays
selectedDates
occurrencesOption
selectedOccurrences
252
monthsOption
selectedMonths
Sets the delivery months of the scheduled orders. Values are 0 11,
which indicate January December.
selectedHours
Identifies the selected hours in an integer array. Values are 0 23, where
0 indicates 12:00, and 23 indicates 23:00 or 11:00 p.m.
selectedMinutes
selectedInterval
Identifies the interval option for the schedule. Selected intervals are
used when creating a periodic schedule. When daysOption parameters
reference this parameter, it is used for creating calendar schedules.
Parameter
Description
intervalOption
The following example shows how you could create a schedule that runs on selected dates in selected months
at a specific hour and time. This schedule is also set to end after 345 occurrences:
The following example shows how you could create a schedule that runs on selected days within a specific
month at a specific hour and minute. This schedule has no end date:
The following example shows how you could create a schedule that runs on the second and third Wednesdays
and the first, third and twenty-eight day of February at a specific hour and minute:
253
254
Parameter
Description
scheduledOrderId
The repository ID of the scheduled order. Note, this is not the ID of the
scheduled order template, but the ID of the scheduled order item.
name
scheduleType
startDate
endDateOption
Options that can be set for the end date of the scheduled order. The
options include none, afterOccurrences or endBy.
numberOfOccurances
endDate
The end date of the scheduled order. Used with the endBy parameter.
daysOption
This calendar property sets the delivery days of the scheduled order.
The options for this property are allDays, selectedDays and
selectedDates.
selectedDays
selectedDates
occurrencesOption
Parameter
Description
selectedOccurrences
monthsOption
selectedMonths
Sets the delivery months of the scheduled orders. Values are 0 11,
which indicate January December.
selectedHours
Identifies the selected hours in an integer array. Values are 0 23, where
0 indicates 12:00, and 23 indicates 23:00 or 11:00 p.m.
selectedMinutes
selectedInterval
Identifies the interval option for the schedule. Selected intervals are
used when creating a periodic schedule. When daysOption parameters
reference this parameter, it is used for creating calendar schedules.
intervalOption
255
Parameter
Description
orderToDuplicate
Parameter
Description
scheduledOrderId
orderId
The ID of the template order with which the scheduled order is associated.
256
Parameter
Description
scheduledOrderId
orderId
The ID of the template order with which the scheduled order is associated.
Actor-Chain
Description
getReadableSchedule
getAllScheduledOrderInfo
The getReadableSchedule actor-chain displays the scheduled order details. This actor-chain is used by other
actors and actor-chains to obtain data regarding scheduled orders. It has the following parameters:
Parameter
Description
scheduledOrderId
scheduledOrder
The ID of the template order with which the scheduled order is associated.
locale
257
The getAllScheduleInfo actor-chain displays the scheduled order details. This actor-chain is used by other
actors and actor-chains and returns only the scheduled object.
Parameter
Description
scheduledOrderId
scheduledOrder
The ID of the template order with which the scheduled order is associated.
locale
258
This actor contains the following actor-chains for working with template orders:
Actor-Chain
Description
commitOrder
validateTemplateOrder
sendCOnfirmationMessage
Parameter
Description
allowEmptyOrders
salesChannel
siteId
createTemplateFromSubmittedOrder
259
Parameter
Description
The e-mail address, obtained from the customers profile. If an e-mail parameter is not
passed in, the e-mail address of the current customer will be used by default.
templateName
The name of the template. If no template name is provided, the template name that is
set on the confirmation object is used.
Reviewing a Template
The ScheduledOrderLookupActor allows you to iterate through a list of scheduled orders for a specific
customer, or other parameter. This actor is located at /atg/commerce/order/scheduled/
ScheduledOrderLookup and uses the scheduledOrderLookup actor-chain.
This actor-chain contains the following parameters. Note that you need to provide only one parameter as the
system cycles through all available parameters. If you include more than one parameter, the extra parameters
will be ignored. :
260
Parameter
Description
itemId
templateId
profileId
siteIds
siteScope
Parameter
Description
orderId
sortDirection
sortField
currentPage
resultsPerPage
261
{
"searchResults": [{
"id": "o500035"
},
{
"id": "o500030"
},
{
"id": "o500001"
},
{
"id": "o490001"
},
{
"id": "o480006"
},
{
"id": "o480001"
},
{
"id": "o120006"
},
{
"id": "o110003"
},
{
"id": "o90007"
},
{
"id": "o90003"
}],
"resultsPerPage": 10,
"totalItemCount": 10,
"currentPage": 0
}
262
Parameter
Description
profileId
sortDirection
sortField
currentPage
resultsPerPage
Actor-Chain
Description
addAdjustment
delteAdjustment
Parameter
Description
adjustmentAmount
adjustmentNote
adjustmentReasonCode
263
Parameter
Description
adjustmentType
Parameter
Description
adjustmentId
adjustmentReasonCode
IPO:commerceItemId=newPrice
264
"http://localhost:8280/rest/model/atg/commerce/custsvc/order/CartModifierActor/
setOrderByCommerceId?ci172000006=1&IPO:ci172000006=19.99"
Actor-Chain
Description
getCurrentCatalogRootCategories
getCategory
getProduct
{"rootCategories": [
{
"id": "homeStoreNonNavigableProducts",
"description": "",
"defaultParentCategory": null,
"displayName": "Non Navigable Products",
"type": null
},
{
"id": "homeStoreRootCategory",
"description": null,
"defaultParentCategory": null,
"displayName": "Home Store Root",
"type": null
265
}
]}
Parameter
Description
categoryId
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.
Parameter
Description
productId
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
catalogs
266
custsvc/catalog/ProductCatalogActor/getProduct"
Search a Catalog
The catalog search REST call uses Endeca catalog search. For information on Endeca catalog searches, refer to
the Commerce Reference Store Installation and Configuration Guide
Note: When a Commerce Service Center agent performs a search, the agents profile is the current profile, but
when Oracle Commerce Platform calls the Endeca catalog search API, the customer profile becomes the current
profile.
To initiate a catalog search call:
Parameter
Description
resultSetSize
Sets the number of results that are displayed per page. The default is 10.
keyword
startDate
Optional. The start date used to search the catalogs. For example, YYYY-MM-DD
HH:MM:SS format, or, 2010-08-11 00:00:00.
endDate
Optional. The end date used to search the catalogs. For example, YYYY-MM-DD
HH:MM:SS format, or, 2010-08-11 00:00:00.
allowEmptySearch
When this parameter is set to true, if there is no search criteria, all catalogs will be
searched.
267
Actor-Chain
Description
setCurrentCatalog
getCurrentCatalog
setDefaultCatalog
Parameter
Description
catalogId
268
Actor-Chain
Description
productPriceRanges
Provides the lowest and highest sale price for a product. These prices are
obtained from the users profile.
skuPrices
Displays either the listPrice and salePrice for a specific SKU if price
lists are enabled. If price lists are not enabled, displays both listPrice and
salePrice.
Parameter
Description
productId
269
Parameter
Description
productId
skuId
Actor-Chain
Description
setCurrentPriceList
getCurrentPriceList
setDefaultPriceList
270
Parameter
Description
priceListId
Parameter
Description
resultSetSize
Allows you to set the number of the results displayed on the page. The
default is 10.
271
Parameter
Description
keyword
startDate
Specifies the start date of a search date range. For example, YYYY-MM-DD
HH:MM:SS format, or, 2010-08-11 00:00:00.
endDate
Specifies the end date of a search date range. For example, YYYY-MM-DD
HH:MM:SS format, or, 2010-08-11 00:00:00.
allowEmptySearch
When set to true, this parameter allows you to search without using a search
criteria.
272
Actor-Chain
Description
getAvailablePromotions
updatePrice
grantPromotion
Add a promotion.
unGrantPromotion
includePromotionInOrder
excludePromotionFromOrder
saveWallet
revertWallet
Parameter
Description
resultsPerPage
{"availablePromotions":[
{
"ignored":false,
"agentGranted":false,
"closenessQualifiers":[],
"close":false,
"considered":false,
"discount":0,
"promotionId":"promo10003",
"usable":true,
"promotionName":"CRS Home - Free Shipping",
"applied":true,
"active":false,
"promotionStateId":"80"
},
{
"ignored":false,
"agentGranted":false,
"closenessQualifiers":[
{
"id":"se-200005",
"name":"Save $10 on all orders over $100"
}
],
"close":true,
"considered":false,
"discount":0,
"promotionId":"promo50012",
"usable":true,
"promotionName":"$10 off Orders over $100",
"applied":false,
"active":false,
"promotionStateId":"82"
}
]}
273
Adding a Promotion
The grantPromotion actor-chain adds a promotion to the order. This actor-chain has the following parameters:
Parameter
Description
promotionId
Removing a Promotion
The unGrantPromotion actor-chain removes a promotion from the order. In Commerce Service Center, only
agent-granted promotions can be removed by agents. This actor-chain has the following parameters:
Parameter
Description
promotionStateId
274
Parameter
Description
promotionId
Parameter
Description
promotionId
275
PromotionWalletActor/saveWallet"
{"closenessQualifiers":[
{"id":"se-200005",
"name":"Save $10 on all orders over $100"}
]}
276
Parameter
Description
keyword
Parameter
Description
dateOption
The date to search for the promotion. This parameter can take the following
values: Today, Start in Next 7 Days, End in Last 7
Days, All Future, or All Expired.
type
The type of promotion to search for. This parameter can take the following
values: " empty, which gets all types, Item Discount, Order
Discount, or Shipping Discount.
hideGlobal
site
Which sites to search for promotions. This parameter can take the following
values: " empty, which gets all sites or site name.
resultsSetSize
Parameter
Description
amount
277
Parameter
Description
comments
{"promotionsLost":"promo50012"}
278
Actor-Chain
Description
createGiftlist
updateGiftlist
addItemToGiftlist
removeItemFromGiftlist
addItemToWishlist
removeItemFromWishlist
moveItemsFromCart
deleteGiftlist
Parameter
Description
isPublished
siteId
279
Parameter
Description
eventName
eventDate
eventType
description
comments
shippingAddressId
instructions
isNewAddress
firstName
middleName
lastName
address1
address2
city
state
postalCode
country
phoneNumber
280
Parameter
Description
isPublished
siteId
eventName
eventDate
eventType
description
comments
shippingAddressId
instructions
isNewAddress
firstName
middleName
lastName
address1
281
Parameter
Description
address2
city
state
postalCode
country
phoneNumber
Parameter
Description
giftlistId
quantity
productId
catalogRefIds
The catalog reference ID of the product being added to the gift list.
siteId
282
Parameter
Description
siteId
quantity
productId
catalogRefIds
The catalog reference ID of the product being added to the wish list.
Parameter
Description
giftlistId
The ID of the gift list from which the items will be removed.
giftitemId
283
Parameter
Description
giftitemId
Parameter
Description
giftlistId
The ID of the gift or wish list to which the items will be moved.
itemIds
quantity
Parameter
Description
giftlistId
284
Actor-Chain
Description
view
giftlistItems
Parameter
Description
giftlistId
{"giftlist": {
"giftlistItems": [],
"instructions": null,
"description": null,
"name": "Valentines",
"public": true,
"date": {"time": 1360816200000},
"type": "Other",
"repositoryId": "gl130271",
"addressId": "230324",
}
}
285
Parameter
Description
giftlistId
286
Parameter
Description
firstName
lastName
eventType
eventDate
sortField
sortDirection
resultsPerPage
currentPage
{"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
}
]
}
287
Parameter
Description
doOwnerSearch
doSiteFilterSearch
includeDisabledSites
sortDirection
sortField
resultsPerPage
currentPage
{
"resultsPerPage": 10,
"totalItemCount": 1,
"currentPage": 0,
"giftlists": [{
"giftlistItems": [],
"instructions": null,
"description": null,
"name": null,
"public": true,
"date": {"time": 1364308351415},
"type": null,
"repositoryId": "gl130274"
"addressId": "230327"
}]
}
288
For information on adding an item to an in-store pickup, refer to Adding Items to a Customers Shopping
Cart (page 218).
289
{
"time": 1364378657000
},
"customerId": "210006",
"orderTotal": 13.75,
"appeasementTotal": -12,
"agentId": "a10001",
"customerEmail": "customer@example.com",
"orderId": "o1200001"
},
{
"creationDate":
{
"time": 1364378689000
},
"customerId": "210006",
"orderTotal": 18.75,
"appeasementTotal": -12,
"agentId": "a10001",
"customerEmail": "customer@example.com",
"orderId": "o1200002"
}
Actor-Chain
Description
approveOrder
rejectOrder
Parameter
Description
approvalId
newOrderId
290
/rest/model/atg/commerce/custsvc/approvals/order/ApproveOrderActor/approveOrder"
Parameter
Description
approvalId
newOrderId
291
Display any promotions that are lost as part of a return or an exchange by calling the
LostPromotionsActor. Note that this data is calculated when the actor is called, but the data is not
saved.
Display any promotions that have been changed as part of the return or exchange process by calling the
changePromotions actor-chain.
5. To complete the return or exchange process, use the confirmReturn actor-chain to confirm that the
item should be returned or exchanged. The confirmation chain can be customized to display different
confirmation details.
6. Once the return or exchange process is complete, you can process items when they have been received back
from the customer by calling the receiveReturnItems actor-chain, and display return history for a specific
order by calling the returnsHistory actor-chain.
The CSRReturnsActor is used when working with returns and exchanges. This actor, along with the
ModifyRefundValuesActor, and the LostPromotionsActor, comprise the agent-based returns and
exchanges functionality. The path to this actor is: atg/commerce/custsvc/returns/
CSRReturnsActor.
This actor contains the following actor-chains:
292
Actor-Chain
Description
createReturn
selectItems
confirmReturn
confirmation
cancelReturnRequest
returnReasons
receiveReturnItems
modifiableRefundsMethodList
applyRefunds
isCurrentOrderReturnable
isItemReturnable
isReturnActive
returnsHistory
returns
nonReturnItemDetails
Actor-Chain
Description
changedPromotions
Creating a Return
The createReturn actor-chain initiates a return request specific to the order ID passed in and sets
the Commerce Service Center environment settings, such as price lists. Note that this actor-chain calls
the StartReturnExchangeProcess form handler. The external createReturn actor-chain uses the
ReturnFormHandler. For information on the external createReturn actor-chain, refer to the Initiating a
Return (page 155) section. Subsequent Return REST calls use this return request for the order specific return
details. It contains the following parameters:
Parameter
Description
newOrderId
293
294
Parameter
Description
processName
jsonReturnRequest
295
"suggestedTaxRefundShare":0,
"quantityReceived":0,
"itemCurrencyCode":"USD",
"returnItemId":"xcr10101",
"actualTaxRefundShare":0,
"refundAmount":50.52,
"shippingGroupId":"xcsg20080",
"quantityReturned":0,
"quantityShipped":1,
"quantityAvailable":1,
"description":"Boyfriend Jeans",
"quantityToReturn":1,
"actualShippingRefundShare":6.31,
"suggestedShippingRefundShare":6.31,
"commerceItemId":"xci1000051",
"catalogRefId":"xsku2519_2",
"suggestedRefundAmount":50.52,
"disposition":null,
"returnReason":"didNotLike"
},
{
"quantityToExchange":0,
"suggestedTaxRefundShare":0,
"quantityReceived":0,
"itemCurrencyCode":"USD",
"returnItemId":"xcr10102",
"actualTaxRefundShare":0,
"refundAmount":51.44,
"shippingGroupId":"xcsg20080",
"quantityReturned":0,
"quantityShipped":1,
"quantityAvailable":1,
"description":"Corduroy Cargo Pants",
"quantityToReturn":1,
"actualShippingRefundShare":6.31,
"suggestedShippingRefundShare":6.31,
"commerceItemId":"xci1000052",
"catalogRefId":"xsku2512_2",
"suggestedRefundAmount":51.44,
"disposition":null,
"returnReason":"defective"
}
],
"processImmediately":false,
"rma":null,
"returnFee":0,
"orderId":"xco30045",
"profile":{
"middleName":null,
"lastName":"Smith",
"id":"se-570085",
"login":"jsmith@example.com",
"firstName":"Joe"
}
}
}
296
{
"reasons": {
"incorrectSize": "Incorrect Size",
"incorrectColor": "Incorrect Color",
"didNotMeetExpectations": "Did Not Meet Expectations",
"didNotLike": "Did Not Like",
"defective": "Defective",
"incorrectItem": "Incorrect Item"
}
}
297
Parameter
Description
returnItemsRequest
returnItemDispositions
receiveItemQuantities
298
Applying Refunds
The applyRefunds actor-chain is used to apply refund type and value to the order. The server-side
sortedRefundMethodList is updated by the UI with the values of the amounts passed in, in the order
in which they are passed in. As such, the inputs for the applyRefund actor-chain should match the
sortedRefundMethodList.
Parameter
Description
returnMethodListSize
The array size to retrieve from the JSP. The array size corresponds to the
number of refund methods available.
Parameter
Description
orderId
299
Parameter
Description
commerceItemId
300
Parameter
Description
orderId
301
"returnItemId":"xc100010"
},
{
"requestId":"xc100005",
"returnItemId":"xc100009"
}
],
"rma":"xc100005",
"createdDateTime":1340764006000,
"orderId":"xco20040"
}
]
}
302
Parameter
Description
creditCardType
creditCardNumber
expirationMonth
expirationYear
firstName
middleName
Parameter
Description
lastName
address1
address2
city
state
country
postalCode
phoneNumber
Actor-Chain
Description
modifyRefundValues
This service allows you to edit the values of a refunded item within an
array.
resetRefundValues
This service call clears and resets all refund values. You can use this
property to edit the default refund value for a returned item, shipping
cost or other adjustment.
303
Parameter
Description
returnItemRefunds
shippingAdjustment
otherAdjustment
Responding to Customers
There are two actors that allow an agent to use the tasks found on the Respond Tab in the UI. These tasks enable
agents to respond to customers using e-mail.
The RespondEmailActor is used by agents to respond to e-mail from a customer. This actor is located at /atg/
svc/agent/ui/formhandlers/RespondEmailActor, and contains the following actor-chains:
304
Actor-Chain
Description
sendEmail
Allows an agent to send e-mail using the Send Email form on the
Respond Tab.
addAttachment
Actor-Chain
Description
discardEmail
Parameter
Description
to
cc
bcc
subject
htmlBody
textBody
Parameter
Description
windowId
fileAsString
contentType
fileSize
fileName
305
Parameter
Description
tempDir
attachmentDisplayName
Discarding an E-Mail
The discardAttachment actor-chain allows an agent to discard an e-mail.
Parameters: None
306
Parameter
Description
to
cc
bcc
subject
htmlBody
Parameter
Description
textBody
doWarnings
doTicketDispositionPrompt
ticketDispositionOptions.dispositionOption
If doTicketDispositionPrompt is enabled, this provides a ticket
disposition option.
ticketDispositionOptions.reasonCode
If doTicketDispositionPrompt is selected, this provides a ticket
note is public.
307
"http://localhost:8280/rest/model/atg/commerce/custsvc/environment/
GlobalInfoActor/globalInfo"
This REST service call returns a server response similar to the following, providing current session values:
{
"currentSite": {
"id": "storeSiteUS",
"name": "CRS Home"
},
"currentSalePriceList": {
"id": "salePrices",
"displayName": "Sale Prices"
},
"currentAgent": {
"id": "Call Center Agent",
"lastName": "Agent",
"login": "Call Center Agent",
"firstName": "Call Center"
},
"currentLocale": {
"language": "en",
"displayName": "English (United States)",
"country": "US"
},
"currentCustomer": {
"middleName": C,
"id": "830013",
"lastName": "Smith",
"login": null,
"firstName": "John"
},
"currentCatalog": {
"id": "homeStoreCatalog",
"status": "other",
"displayName": "Home Store Catalog"
},
"currentCallState": {
"startTime": null,
"callActive": false
},
"currentOrder": {"id": "o99660003",
"currentPriceList": {
"id": "listPrices",
"displayName": "List Prices"
},
"currentTicket": {"id": "5501"}
}
308
This REST service call returns a server response similar to the following, providing a list of sites:
{
"groupedSites":
[
{
"id": "storeSiteUS",
"name": "CRS Store"
},
{
"id": "homeSite",
"name": "CRS Home"
},
],
"ungroupedSites": []
}
Selecting a Site
The ChangeSiteActor contains the selectSite actor-chain that allows an agent to select a specific site. This
actor can be configured to present ticket disposition warnings and prompts. The path for this actor is /atg/
svc/agent/environment/ChangeSiteActor.
Parameter
Description
siteId
doWarnings
doTicketDispositionPrompt
dispositionOption
reasonCode
ticketNote
publicNote
309
{
"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
{"messages":[
{
"summary":"No default site has been configured.",
"params":null,
"type":"warning",
"requestUrl":"/rest/model/atg/userprofiling/InternalProfileActor/
login-success?atg-rest-output=json&_requestid=63",
"messageDetails":[],
"timestamp":{"time":1364498690397},
"priority":-5,
"messageGroup":null,
"datetime":{"time":1364498690397},
"identifier":null
},
{
"summary":"First valid active site has been chosen.",
"params":null,
"type":"information",
"requestUrl":"/rest/model/atg/userprofiling/InternalProfileActor/
login-success?atg-rest-output=json&_requestid=63",
"messageDetails":[],
310
"timestamp":{"time":1364498690486},
"priority":-10,
"messageGroup":null,
"datetime":{"time":1364498690486},
"identifier":null
}
]}
{
"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
}
311
If you create an actor that requires a disposition message or error, it must provide information for the
environmentChangeState service. The following example shows how the changeOrderActor includes the
parameters referenced by the environmentChangeState service and defines the confirm actor-chain.
Note: The three environmentChangeState modifications are identified by comments in this example:
312
ShouldDiscardTicket" var="shouldDiscardTicketParamStack">
<input name="immediately" value="false" />
<input name="ticket" value="${nucleus['/atg/svc/agent/environment/
EnvironmentTools'].activeTicket}" />
<oparam name="output">
<output id="isDiscardable" name="isDiscardable"
value="${shouldDiscardTicketParamStack.isDiscardable}" />
</oparam>
</droplet>
</actor-chain>
<!-- End changes -->
<actor-chain id="error" transaction="TX_SUPPORTS">
<component id="fh" name="/atg/commerce/custsvc/environment/ChangeOrder"
component-var="fh">
<output id="formError" name="formError" value="${fh.formError}"/>
<output id="formExceptions" name="formExceptions" value="${fh.formExceptions}"
filter-id="detailed"/>
</component>
</actor-chain>
313
314
This section provides general information about and instructions for using the Oracle Commerce Platform
Legacy REST Web Services interface.
Nucleus Components
The URL for addressing a Nucleus component includes /bean/ in its application path. The following example
shows the beginning of the URL for a Nucleus component.
http://servername:port/rest/bean/
You can use URLs to invoke methods and get or set property values of Nucleus components by including the
names of methods and properties in the application path of the component. Separate the name of the method
or property with a forward slash as if it were a separate container. For example, the following URL addresses the
running property of the atg/dynamo/Configuration component.
http://servername:port/rest/bean/atg/dynamo/Configuration/running
See information about performing operations with Nucleus component properties and methods in Working
with Legacy REST Components (page 343) and Invoking Legacy REST Component Methods (page 345).
Repositories
The URL for addressing a repository item with the Legacy REST Web Services includes /repository/ in its
application path. The following example shows the beginning of the URL for a repository item.
http://servername:port/rest/repository/
317
You can address specific repository items and get or set repository item property values. Include the names
of repository items and values in the application path. Separate the names and values with a forward slash
as if it were a separate container. For example, the following URL addresses the user repository item in the
ProfileAdapterRepository repository.
http://servername:port/rest/repository/atg/userprofiling/
ProfileAdapterRepository/user
The following URL addresses a specific user record in the user repository item. The value of the id property at
the end of the path indicates which user.
http://servername:port/rest/repository/atg/userprofiling/
ProfileAdapterRepository/user/210002
The following URL addresses a specific property of a user record in the user repository item.
http://servername:port/rest/repository/atg/userprofiling/
ProfileAdapterRepository/user/210002/login
See information about performing operations with repositories in Working with Repositories in Legacy
REST (page 354).
Client Software
You can use any means of transmitting HTTP requests to the Legacy REST Web Services that you wish. Any client
software that is capable of sending and receiving messages via HTTP will be adequate. Select the client software
that you use according to the requirements of your environment.
Oracle Commerce Platform Clients for the Legacy REST Web Services
Oracle Commerce Platform provides two client libraries that you can use to interact with Legacy REST Web
Services. These clients make the Legacy REST Web Services easier to use by hiding the complexity of creating
connections, assembling payloads for requests, and processing responses. See information about the clients in
Legacy Rest Client Libraries (page 381).
318
Logging In
Before you can use Legacy REST Web Services you must log in to open an authorized HTTP session. When the
server receives a log in request for a valid user account, it authenticates the user and returns a session identifier
if the authentication is successful.
The procedure for logging in to the Legacy REST Web Services server is different for external and internal users.
External users are customer or other users of outward or customer-facing Web sites. Internal users are those
who have access to agent-facing servers, such as call center agents using Oracle Commerce Service Center. See
specific procedures with examples in Logging In as an External User (page 319) and Logging In as an Internal
User (page 320).
319
*
Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 8280 (#0)
> POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1
> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5
> Host: myserver:8280
> Accept: */*
> Content-Type: application/xml
> Content-Length: 71
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
* Added cookie JSESSIONID="7978B952714AB08BEB006A348A25ADB0" for
* domain myserver, path /, expire 0
< Set-Cookie: JSESSIONID=7978B952714AB08BEB006A348A25ADB0; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9y
bUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
* Added cookie DYN_USER_ID="120001" for domain myserver, path /, expire 1290872360
< Set-Cookie: DYN_USER_ID=120001; Expires=Sat, 27-Nov-2010 15:39:20 GMT; Path=/
* Added cookie DYN_USER_CONFIRM="bca3eb6c2cdeb0e4a625c7165a088e2e" for domain
myserver, path /, expire 1290872360
< Set-Cookie: DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e;
Expires=Sat, 27-Nov-2010 15:39:20 GMT; Path=/
< Content-Type: application/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Thu, 28 Oct 2010 15:39:20 GMT
<
<?xml version="1.0" encoding="UTF-8"?>
<atgResponse>120001</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
320
Include the atg-rest-return-form-handler-exceptions control parameter when you invoke this form
handler. This will cause the server to return exceptions that occur during the log in operation. If you do not
include this control parameter, you will not be able to distinguish between a successful attempt to log in and
one that fails. See Success and Failure Responses for Internal User Log In (page 321).
<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.
321
Logging Out
Users end their Legacy REST Web Services session by logging out. Once logged out, no client will be able to
perform Legacy REST Web Services operations using the session ID that was presented with the log out request.
Invoke the /atg/userprofiling/ProfileServices.logoutUser method to log out of the Legacy REST
Web Services server. Use the HTTP POST method.
The following example shows an HTTP request to log out of a Legacy REST Web Services session.
curl -v -b cookies.txt -X POST \
http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/logoutUser
*
*
*
>
>
>
>
>
>
>
<
<
<
<
322
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
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
323
The Legacy REST Web Services server will call the loginUser method with the arguments in the positional
parameters arg1 and arg2 in that sequence. The method definition for loginUser is shown below. See
information about invoking methods in Invoking Legacy REST Component Methods (page 345).
The Legacy REST Web Services server can interpret message body parameters in XML, JSON or URL query
strings. Make sure you set the correct Content-Type value for the markup that you use.
<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.
{
"login": "Username",
"password": "Password",
"atg-rest-user-input": "MyMessageId"
}
Make sure that you specify Content-Type: application/json in the HTTP message.
The Legacy REST Web Services server will only accept parameters in the message body of a POST or PUT HTTP
request. If you need to use the GET or DELETE methods, you need to include data with your request, and you
cannot include URL parameters, use the atg-rest-view and atg-rest-http-method control parameters. See
Handling POST Requests as Other Methods (page 318).
324
Include the parameters in standard URL query string format as shown in the example below. Include each
parameter in a separate name and value pair. Use the name of the parameter as the name for the pair. For
positional parameters that do not have names, use the arg1, arg2, arg3 convention as the names for the pairs.
See Positional Parameters (page 323).
arg1=MyUsername&arg2=MyPassword&atg-rest-user-input=MyMessageId
URL encode any special URL characters in the parameter values. Make sure that you specify Content-Type:
application/x-www-form-urlencoded in the HTTP message.
Value Type
Values Accepted
String
Number
Boolean
true or false
325
http://myserver:7003/rest/bean/atg/MyDog/tricks?atg-rest-json-input=true
Value Type
Format
Array
<array-element-class>:[value1,value2,...,valueN]
For example:
java.lang.String:[foo,bas,baz]
Collection
<collection-container-class>:<element-class>:
[value1,value2,...,valueN]
For example:
java.util.ArrayList:java.lang.String:[foo,bas,baz]
Map
<map-class>:<key-class>:<value-class>:
[key1=value1,key2=value2,key3=value3]
For example:
java.util.HashMap:java.lang.String:java.lang.String:
[foo=football,baz=basketball,bas=baseball]
If your input is in JSON format, you can use the atg-rest-param-class-types control parameter to specify
Java classes. The atg-rest-param-class-types parameter includes two components, container-class
and element-class. Include this attribute in your JSON input as shown below.
{'atg-rest-param-class-types':{'container-class':
'java.util.ArrayList','element-class':
'java.lang.String'},'arg1':['sit','stay','speak']}
See information about the atg-rest-param-class-types parameter in the Adding Control Parameters (page
61) section.
Legacy REST Web Services are configured to append values to repository item properties using the atg-restappend-multi-values control parameter. For information this parameter, refer to the Using Multiple Values in
Input (page 325) section.
326
Note: The Legacy REST Web Services server is configured to append values to repository item properties that
accept multiple values by default. The appendMultiValuesByDefault configuration property controls this
behavior for repository item properties. If you have reconfigured this setting, set the atg-rest-appendmulti-values control parameter to true for each Legacy REST Web Services request that should append the
new value.
327
rest-class-type control parameter specifies the Java class of the object. Use either JSON or XML to enclose
The following example shows a POST request to set an object property value for a Nucleus component.
$ curl -v -b cookies.txt -X POST -H "Content-Type: application/json" -d
"{"arg1":{"atg-rest-class-type":"atg.MyObjectValue",
"name":"Berthoud","height":"1"}}"
http://myserver:7003/rest/bean/atg/MyDog/objectvalue
* About to connect() to myserver port 7003 (#0)
*
Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 7003 (#0)
> POST /rest/bean/atg/MyDog/objectvalue HTTP/1.1
> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/
0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
> Host: myserver:7003
> Accept: */*
> Cookie: JSESSIONID=
llf3PN8N0CfQ6h41Y278NfLjvCJZn6CR8ydhQRbg7GTQ7Nn5mW8p!1359398113;
DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001
> Content-Type: application/json
> Content-Length: 69
>
< HTTP/1.1 200 OK
< Date: Wed, 29 Feb 2012 05:52:39 GMT
< Transfer-Encoding: chunked
< Content-Type: application/json; charset=UTF-8
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=
328
329
330
331
The following example shows a Legacy REST Web Services request that includes the atg-rest-output control
parameter. The control parameter specifies that data should be returned using XML markup.
curl -v -b cookies.txt -X GET \
http://servername:port/rest/bean/atg/dynamo/Configuration?atg-rest-output=xml
JSON Output
The following example shows JSON output. Notice how string values are surrounded by quotes, numerical
values have no quotes, multivalve elements are surrounded by brackets, and references to repository items are
URLs to the item referenced. Note that multivalve elements will be URLs also, but in this example, the abcArray
has been expanded.
{
"myClass": "class atg.rest.processor.MockObject",
"size": 10,
"abcArray": {
"type": "int",
"elements": [
0,
1,
2,
3
]
},
"product": "http://localhost/rest/repository/atg/commerce/catalog/
ProductCatalog/product/prod12345"
}
XML Output
The following example shows XML output.
<atgResponse>
<organizationPathCache>
<atgRestComponentPath>/atg/userprofiling/OrganizationPathCache
</atgRestComponentPath>
</organizationPathCache>
<rootOrganizationPrimaryKey>root</rootOrganizationPrimaryKey>
[Additional property values omitted to save space]
<roles>
<element>
- RepositoryItemGroupRole:
--> name: Young
--> primary key: Young__grouprole
</element>
<element>
- RepositoryItemGroupRole:
--> name: WomenOnly
--> primary key: WomenOnly__grouprole
332
</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>
[Additional property values omitted to save space]
</atgResponse>
Identifying a Response
You can include an identifying string with a Legacy REST Web Services request and the server will include that
string in the response it returns. One use of this function is to identify the response to an asynchronous Legacy
REST Web Service request.
To specify the identifying string for a Legacy REST Web Services response, include the atg-rest-user-input
control parameter in your HTTP request. Set the value of the control parameter to the identifying string. See
Adding Control Parameters (page 61).
The following example shows a Legacy REST Web Services request that includes the atg-rest-user-input
control parameter.
333
334
<
<?xml version="1.0" encoding="UTF-8"?>
<atgResponse>
[Additional property values omitted to save space]
<creditCards>http://myserver:8080/rest/repository/atg/userprofiling/
ProfileAdapterRepository/user/130001/creditCards</creditCards>
[Additional property values omitted to save space]
</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
The example below shows a collection value that has been expanded. The Legacy REST Web Services request
sets the atg-rest-show-rest-paths control parameter to false.
curl -v -b cookies.txt -X GET \
http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/
user/130001/?atg-rest-show-rest-paths=false
* About to connect() to myserver port 8080 (#0)
*
Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 8080 (#0)
> GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/?
atg-rest-show-rest-paths=false HTTP/1.1
> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5
> Host: myserver:8080
> Accept: */*
> Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543;
DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
* Replaced cookie JSESSIONID="9D730DE9D4A7C250994F20363ACC3FA6" for domain
myserver, path /, expire 0
< Set-Cookie: JSESSIONID=9D730DE9D4A7C250994F20363ACC3FA6; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybU
xpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< Content-Type: application/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Fri, 05 Nov 2010 22:04:32 GMT
<
<?xml version="1.0" encoding="UTF-8"?>
<atgResponse>
[Additional property values omitted to save space]
<creditCards>
<element>
<key>MyOtherCard</key>
<value>
<atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository
</atgRestComponentPath>
335
<atgRestItemDescriptor>credit-card</atgRestItemDescriptor>
<atgRestRepositoryId>usercc10003</atgRestRepositoryId>
</value>
</element>
<element>
<key>MyCard</key>
<value>
<atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository
</atgRestComponentPath>
<atgRestItemDescriptor>credit-card</atgRestItemDescriptor>
<atgRestRepositoryId>usercc10001</atgRestRepositoryId>
</value>
</element>
</creditCards>
[Additional property values omitted to save space]
</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
336
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"
]}
337
The following example shows the same property value in JSON format.
{"creditCards": { "MyCard": "http://myserver:8080/rest/repository/atg/
userprofiling/ProfileAdapterRepository/credit-card/usercc10001",
"MyOtherCard": "http://myserver:8080/rest/repository/atg/userprofiling/
ProfileAdapterRepository/credit-card/usercc10003" }}
338
The following example shows the same property value in JSON format.
{"previousPasswords": [
"17d0b74864b89840e07f08f46dd72f90fed59b62d476639c25667a3b3f74bdf5",
"914eb28cb2996739bdd33ed74deed1005ff1fd40489583d22bd35d5a8344fa6c"
]}
Return Depth
You can control the number of nested levels of property information that the Legacy REST Web Services server
will return when you request property values. Use the atg-rest-depth control parameter to specify the
number of levels that will be included in returned data.
The number of nested levels you can expand in returned data is limited by the maxDepthAllowed configuration
for the Legacy REST Web Services server.
The default number of levels is zero which returns only the immediate properties of the Nucleus component you
specify in your request. If one of those properties includes multiple values or is a complex object, the returned
data will include only the REST path of the property value. For example:
<creditCards>http://myserver:8080/rest/repository/atg/userprofiling/
ProfileAdapterRepository/user/130001/creditCards</creditCards>
If you set the return depth to one, the returned data will expand properties that contain multiple values and
complex objects. The individual values within them will be included in the returned data. For example:
339
<creditCards>
<element>
<key>MyOtherCard</key>
<value>
<atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository
</atgRestComponentPath>
<atgRestItemDescriptor>credit-card</atgRestItemDescriptor>
<atgRestRepositoryId>usercc10003</atgRestRepositoryId>
</value>
</element>
<element>
<key>MyCard</key>
<value>
<atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository
</atgRestComponentPath>
<atgRestItemDescriptor>credit-card</atgRestItemDescriptor>
<atgRestRepositoryId>usercc10001</atgRestRepositoryId>
</value>
</element>
</creditCards>
340
341
342
Request Component
Value
HTTP Method
GET
Functional Parameters
None
URL
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
*
*
*
>
>
>
>
343
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
Request Component
Value
HTTP Method
POST or PUT
Functional Parameters
URL
The following example shows a Legacy REST Web Services request that sets the value of the atg/
userprofiling/passwordchecker/PasswordRuleChecker.enabled property.
curl -v -b cookies.txt -X POST \
-H "Content-Type: application/xml" \
-d "<parameters><arg1>false</arg1></parameters>" \
344
http://myserver:8080/rest/bean/atg/userprofiling/passwordchecker/
PasswordRuleChecker/enabled
* About to connect() to myserver port 8080 (#0)
*
Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 8080 (#0)
> POST /rest/bean/atg/userprofiling/passwordchecker/PasswordRuleChecker/
enabled HTTP/1.1
> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5
> Host: myserver:8080
> Accept: */*
> Cookie: JSESSIONID=7205768051AC55AAFD5020D8931C71A7
> Content-Type: application/xml
> Content-Length: 43
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9ybUxp
Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ==
< Content-Type: application/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Tue, 26 Oct 2010 14:58:28 GMT
<
<?xml version="1.0" encoding="UTF-8"?>
<atgResponse>true</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
Request Component
Value
HTTP Method
POST
Functional Parameters
URL
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.
345
346
Request Component
Value
HTTP Method
POST
Functional Parameters
Submit the required property values of the form as functional parameters. Name
each parameter with the property name it corresponds to. See Submitting
Legacy REST Form Values (page 347).
URL
The following example shows a Legacy REST Web Services request that invokes the create operation of /atg/
store/profile/RegistrationFormHandler. The HTTP request includes functional parameters to supply
the value property of the form handler. The data type of the value property is java.util.Dictionary;
parameter names such as value.password correspond to the password key in the dictionary value.
curl -v -b cookies.txt -X POST \
-H "Content-Type: application/json" \
-d "{ "value.email":"sheroux@example.com", "value.password":"mypassword",
"value.confirmPassword":"mypassword", "value.firstName":"Severe",
"value.lastName":"Heroux" }" \
http://myserver:8080/rest/bean/atg/store/profile/RegistrationFormHandler/create
* About to connect() to myserver port 8080 (#0)
*
Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 8080 (#0)
> POST /rest/bean/atg/store/profile/RegistrationFormHandler/create HTTP/1.1
> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5
> Host: myserver:8080
> Accept: */*
> Cookie: DYN_USER_ID=140003; JSESSIONID=1DEDBDEE3BF322FA71AFE89438DCCF9E;
DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b
> Content-Type: application/json
> Content-Length: 147
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm9ybUxpY2
Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
* Replaced cookie DYN_USER_ID="140003" for domain myserver, path /,
expire 1291317542
< Set-Cookie: DYN_USER_ID=140003; Expires=Thu, 02-Dec-2010 19:19:02 GMT; Path=/
* Replaced cookie DYN_USER_CONFIRM="1231cf3e7573bf936dbd29dbbbfe150b" for
domain myserver, path /, expire 1291317542
< Set-Cookie: DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b; Expires=Thu,
02-Dec-2010 19:19:02 GMT; Path=/
< Content-Type: application/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Tue, 02 Nov 2010 19:19:02 GMT
<
<?xml version="1.0" encoding="UTF-8"?>
<atgResponse>true</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
347
property hold the values that would be entered in user interface fields on a registration form. To invoke the /
atg/store/profile/RegistrationFormHandler form handler, you must include a functional parameter for
value.email, value.password, value.confirmPassword, value.firstName, and value.lastName.
The following JSON data contains the functional parameters required by the /atg/store/profile/
RegistrationFormHandler form handler.
{ "value.email":"sheroux@example.com", "value.password":"mypassword",
"value.confirmPassword":"mypassword", "value.firstName":"Severe",
"value.lastName":"Heroux" }
The following example shows the response to a successful Legacy REST Web Services request to invoke /atg/
userprofiling/InternalProfileFormHandler/login. The response includes an empty exceptions
element because no exceptions occurred.
<atgResponse>
<class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class>
<exceptions/>
<result>true</result>
</atgResponse>
Note: if you choose to include both exceptions and form handler properties in a Legacy REST Web
Services request, the class element in the atgResponse will contain the following value: class
atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Legacy
REST Form Handler Properties (page 348).
348
server will include the property values in a component element in the HTTP response. Set the value of the
control parameter to true.
The following example shows the response to a Legacy REST Web Services request to invoke /atg/store/
profile/RegistrationFormHandler/create. The response includes a component element that contains
the property values of the RegistrationFormHandler component.
<atgResponse>
<class>class atg.rest.processor.BeanProcessor$FormHandlerProperties</class>
<component>
<absoluteName>/atg/dynamo/servlet/pipeline/RequestScopeManager/
RequestScope-409/atg/store/profile/RegistrationFormHandler</absoluteName>
<addCommerceItemInfos/>
<addressIdValueMapKey>addressId</addressIdValueMapKey>
[Additional property values omitted to save space]
<valueMap>http://myserver:8080/rest/bean/atg/dynamo/servlet/pipeline/
RequestScopeManager/RequestScope-409/atg/store/profile/
RegistrationFormHandler/valueMap</valueMap>
<verifyPasswordSuccessURL/>
</component>
<result>true</result>
</atgResponse>
Note: if you choose to include both exceptions and form handler properties in a Legacy REST Web
Services request, the class element in the atgResponse will contain the following value: class
atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Legacy
REST Form Handler Exceptions (page 348).
349
Request Component
Value
HTTP Method
GET or POST
Functional Parameters
Do not submit functional parameters when accessing JSPs via the Legacy REST
Web Services. Pass parameters in the URL that corresponds to the JSP.
The format of the parameters that you pass in the URL is configured by the URL
recoding feature of the Oracle Commerce Platform. The developers who design
the JSP and the URL recoding template control the parameter format. See URL
Templates for Legacy REST Web Services JSPs (page 351).
URL
Include the component pathname that corresponds to the JSP in the application
path after /rest/service/. Include the parameters at the end of the path in the
format expected by the template.
The URL that corresponds to a JSP is configured by the URL recoding feature of
the Oracle Commerce Platform. The developers who design the JSP and the URL
recoding template control the URL and the parameter format. See URL Templates
for Legacy REST Web Services JSPs (page 351).
The following example shows a Legacy REST Web Services request that invokes a JSP. The application path and
parameters in the URL are the controlled by the example configurations shown in URL Templates for Legacy
REST Web Services JSPs (page 351). The code of the JSP itself is shown in Example Legacy REST Web Services
JSP (page 353).
$ curl -v -b cookies.txt -X GET http://myserver:7003/rest/service/
atg/AnyComponent/xprod2083,foo
350
351
<ATG11dir>/home/servers/servername/localconfig/atg/rest/processor/templates/
MyTemplate.properties
$class=atg.repository.seo.IndirectUrlTemplate
# Url template format
urlTemplateFormat=/rest/service/atg/AnyComponent/{item.id},{mystring}
# Regex that matches above format
indirectRegex=.*/rest/service/atg/AnyComponent/([^/].*?),([^/].*?)$
# Regex elements
regexElementList=item | id | /atg/AnyComponent\:product, mystring | string
# Forward Url template
forwardUrlTemplateFormat=/mymodule/WEB-INF/rest/myRestJsp.jsp?
productId\={item.id}&myString\={mystring}
# Web App registry
webAppRegistry=/atg/registry/WebApplicationRegistry
Note: See comprehensive information about configuring the URL recoding feature of the Oracle Commerce
Platform in the Platform Programming Guide.
<ATG11dir>/home/servers/servername/localconfig/atg/rest/processor/
ServiceProcessor.properties
352
The example ServiceProcessor.properties file shown below adds a URL template component to the
templates property.
templates+=/atg/rest/processor/templates/MyTemplate
<%-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>
353
Request Component
Value
HTTP Method
GET
Functional Parameters
None
URL
Include the component pathname of the repository in the application path after
/rest/repository/. Include the name of the item type at the end of the path.
The following example shows a Legacy REST Web Services request that lists the repository items of the user
item type in the atg/userprofiling/ProfileAdapterRepository repository.
354
<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
Request Component
Value
HTTP Method
GET
Functional Parameters
None
URL
Include the component pathname of the repository in the application path after
/rest/repository/. Include the name of the item type and the identifier of the
specific item at the end of the path.
The following example shows a Legacy REST Web Services request that lists the properties of a specific
repository item of the user item type in the /atg/userprofiling/ProfileAdapterRepository repository.
355
2UvMCBCMkNMaWNlbnNlLzAgIF0=
< Content-Type: application/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Fri, 29 Oct 2010 16:40:51 GMT
<
<?xml version="1.0" encoding="UTF-8"?>
<atgResponse>
<repositoryId>130001</repositoryId>
<securityStatus>4</securityStatus>
[Additional property values omitted to save space]
<ThirtySomethings>false</ThirtySomethings>
<MenOnly>false</MenOnly>
<Fashionista>false</Fashionista>
<Young>false</Young>
<WomenOnly>false</WomenOnly>
</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
Request Component
Value
HTTP Method
GET
Functional Parameters
None
URL
Include the component pathname of the repository in the application path after
/rest/repository/. Include the name of the item type, the identifier of the
specific item, and the name of the property at the end of the path.
The following example shows a Legacy REST Web Services request that returns the lastPurchaseDate
property of a specific repository item of the user item type in the atg/userprofiling/
ProfileAdapterRepository repository.
356
Request Component
Value
HTTP Method
GET
Functional Parameters
Include the atg-rest-rql functional parameter. Set its value to the RQL query
you want to execute.
If you include this parameter as a URL query string, make sure that you URL
encode the RQL query. For example, the query ALL RANGE +4 should be
encoded as ALL+RANGE+%2B4.
URL
Include the component pathname of the repository item type that you want to
query in the application path after /rest/repository/.
The following example shows a Legacy REST Web Services request that performs an RQL query. It returns the
first four items of item type product in the /atg/commerce/catalog/ProductCatalog repository.
357
Note: You can include the atg-rest-rql functional parameter in the message body of a POST HTTP request
if you prefer not to URL encode your RQL queries. Use the atg-rest-view control parameter to instruct the
Legacy REST Web Services server to handle your POST request as a GET request. See Handling POST Requests as
Other Methods (page 318).
Note: Do not include parameters in the RQL queries that you perform via the Legacy REST Web Services. Make
sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL
queries in the Repository Guide
358
Request Component
Value
HTTP Method
POST
Request Component
Value
Functional Parameters
Include all required property values for the new repository item as functional
parameters with the Legacy REST Web Services request.
URL
Include the component pathname of the repository in the application path after
/rest/repository/. Include the name of the item type at the end of the path.
The following example shows a Legacy REST Web Services request that creates a new repository item in the /
atg/userprofiling/ProfileAdapterRepository repository. The returned data includes all the property
values for the new item.
359
<registrationDate>2010-11-01 13:35:28.742</registrationDate>
<dateOfBirth/>
<member>false</member>
<firstName>Roland</firstName>
<billingAddress/>
[Additional property values omitted to save space]
<Young>false</Young>
<WomenOnly>false</WomenOnly>
</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
Transient Items
Use the atg-rest-transient control parameter to create transient repository items. Set the value of the
parameter to true. The following command creates a transient repository item.
curl -v -b cookies.txt -X POST -H "Content-Type: application/xml" \
-d "<parameters><login>agold</login><lastName>Gold</lastName>
<firstName>Abbey</firstName><email>agold@example.com</email>
<password>mypassword</password></parameters>" \
http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/
user?atg-rest-transient=true
Request Component
Value
HTTP Method
PUT
Functional Parameters
Include the new values for each property you are updating as functional
parameters with the Legacy REST Web Services request.
URL
Include the component pathname of the repository in the application path after
/rest/repository/. Include the name of the item type and the item identifier
at the end of the path.
The following example shows a Legacy REST Web Services request that updates two properties of an existing
repository item in the /atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X PUT \
-H "Content-Type: application/xml" \
-d "<parameters><middleName>Desire</middleName><email>agoldie@example.com</email>
</parameters>" \http://myserver:8080/rest/repository/atg/userprofiling/
360
ProfileAdapterRepository/user/130034
* About to connect() to myserver port 8080 (#0)
*
Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 8080 (#0)
> PUT /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/
130034 HTTP/1.1
> User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5
> Host: myserver:8080
> Accept: */*
> Cookie: DYN_USER_ID=140003; JSESSIONID=B6D3509A03881D9CE1A1370434AD18CB;
DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b
> Content-Type: application/xml
> Content-Length: 90
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
* Replaced cookie JSESSIONID="6A9888BA9F4035AF606AE7E40A435451" for domain
myserver, path /, expire 0
< Set-Cookie: JSESSIONID=6A9888BA9F4035AF606AE7E40A435451; Path=/
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQbGF0Zm
9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0=
< Content-Type: application/xml;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Mon, 01 Nov 2010 19:40:41 GMT
<
<?xml version="1.0" encoding="UTF-8"?>
<atgResponse>true</atgResponse>
* Connection #0 to host myserver left intact
* Closing connection #0
Request Component
Value
HTTP Method
DELETE
Functional Parameters
Include the new values for each property you are updating as functional
parameters with the Legacy REST Web Services request.
URL
Include the component pathname of the repository in the application path after
/rest/repository/. Include the name of the item type and the item identifier
at the end of the path.
The following example shows a Legacy REST Web Services request that deletes an existing repository item in the
/atg/userprofiling/ProfileAdapterRepository repository.
361
362
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"/>
363
The next sample extends the previous one by adding a component attribute to the property tag and using
that in combination with the target tag. This demonstrates how the value of a property can come from another
Nucleus component. (Note that the component attribute can only reference a Nucleus component.) Dot
notation can be used in the target attribute when the component attribute is used.
<rest-filtering>
<component name="/some/Component" default-include="true">
<property name="property1" hidden="true"/>
<property name="property2" writable="false"/>
<property name="virtual1" target="property2"/>
<property name="virtual2" target="property2.subproperty"/>
<property name="virtual3" component="/some/other/Component" target="aProperty"/>
</component>
<component name="/some/Repository" default-include="true">
<item-descriptor name="anItemDescriptorName">
<property name="repProperty1" hidden="true"/>
<property name="repProperty2" writable="false"/>
<property name="repVirtual1" target="repProperty2"/>
<property name="repVirtual2" target="repProperty2.subproperty"/>
<property name="repVirtual3" component="/some/other/Component"
target="aProperty"/>
</item-descriptor>
</component>
</rest-filtering>
Finally, if you need to write custom code to specify your value, then you must use the property-customizer
attribute, as shown in the following sample.
<rest-filtering>
<component name="/some/Component" default-include="true">
<property name="property1" hidden="true"/>
<property name="property2" writable="false"/>
<property name="virtual1" target="property2"/>
<property name="virtual2" target="property2.subproperty"/>
<property name="virtual3" component="/some/other/Component" target="aProperty"/>
<property name="virtual4" property-customizer="some.class.Here"/>
</component>
<component name="/some/Repository" default-include="true">
<item-descriptor name="anItemDescriptorName">
<property name="repProperty1" hidden="true"/>
<property name="repProperty2" writable="false"/>
<property name="repVirtual1" target="repProperty2"/>
<property name="repVirtual2" target="repProperty2.subproperty"/>
<property name="repVirtual3" component="/some/other/Component"
target="aProperty"/>
<property name="repVirtual4" property-customizer="some.class.Here"/>
</item-descriptor>
</component>
</rest-filtering>
364
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.
<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>
<rest-filtering>
<template id="myfiltertemplate" name="/atg/MyDog" default-include="true">
365
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.
{
"<componentName>":
[
{
"item-descriptor": "<itemDescriptorName>",
"depth": <depthInt>,
"properties":
{
"<propertyName>":
{
"hidden": <boolean>,
"writable": <boolean>,
"target": "<target-dot-notation>",
"component": "<component-path>",
"property-customizer": "<customizer-class-name>"
}, ...
}, ...
}, ...
366
], ...
}
For example, the following atg-rest-property-filters control parameter value specifies that only the
wishlist property will be returned for user repository items. It also specifies that only the eventType and
published values will be returned for the wishlist property.
{
"/atg/userprofiling/ProfileAdapterRepository": [
{
"item-descriptor": "user",
"depth": 0,
"properties": {
"wishlist": {
}
}
}
],
"/atg/commerce/gifts/Giftlists": [
{
"item-descriptor": "gift-list",
"depth": 1,
"properties": {
"eventType": {
},
"published": {
}
}
}
]
}
The REST Web Service server will check several configuration parameters before accepting filters supplied
with the atg-rest-property-filters control parameter. These configuration properties control whether certain
types of per-request filtering will be accepted. There are individual configuration properties for requests
that will return JSON and XML output. See information about the following properties in /atg/rest/output/
JSONOutputCustomizer (page 371) and /atg/rest/output/XMLOutputCustomizer (page 372).
enablePerRequestFilters
enablePerRequestComponentFilters
enablePerRequestRepositoryFilters
enablePerRequestClassFilters
367
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
},
368
369
/atg/rest/Configuration
This section explains configuration properties that are set on the /atg/rest/Configuration Legacy REST
Web Services component.
Property
Description
defaultOutputCustomizer
This configuration property controls the markup that the Legacy REST
Web Services server uses for returned data. See Choosing Output
Markup (page 331). The following example specifies that the server
should use XML format for the data it returns.
defaultOutputCustomizer=/atg/rest/output/
XMLOutputCustomizer
maxDepthAllowed
/atg/rest/processor/BeanProcessor
This section explains configuration properties that are set on the /atg/rest/processor/BeanProcessor
component for Legacy REST Web Services.
Property
Description
returnFormHandlerExceptionsByDefault
returnFormHandlerPropertiesByDefault
370
/atg/rest/output/JSONOutputCustomizer
This section explains configuration properties that are set on the /atg/rest/output/
JSONOutputCustomizer component for Legacy REST Web Services.
Property
Description
enableFormatDateOutput
enablePerRequestComponentFilters
371
Property
Description
enablePerRequestRepositoryFilters
enablePerRequestClassFilters
showRestPaths
/atg/rest/output/XMLOutputCustomizer
This section provides information about configuration properties that may be set on the /atg/rest/output/
XMLOutputCustomizer component for Legacy REST Web Services
372
Property
Description
enableFormatDateOutput
enablePerRequestComponentFilters
enablePerRequestRepositoryFilters
373
Property
Description
enablePerRequestClassFilters
showRestPaths
/atg/rest/processor/RepositoryProcessor
This section explains configuration properties that are set on the /atg/rest/processor/
RepositoryProcessor component of the Legacy REST Web Services.
Property
Description
acceptJSONInput
374
Property
Description
appendMultiValuesByDefault
/atg/rest/processor/RestSecurityProcessor
This section explains configuration properties that are set on the /atg/rest/processor/
RestSecurityProcessor component of the Legacy REST Web Services.
Property
Description
allowAccessForUnsecuredRepository
375
To understand the security system used by the Legacy REST Web Services server you must understand the
system used by the Oracle Commerce Platform. See Managing Access Control in the Platform Programming Guide.
376
<default-acl value="Profile$login$#username#:read,write,execute"/>
</rest-security>
377
<rest-security>
<default-acl>Profile$role$restUser:read,write,execute"</default-acl>
<resource component="/some/Component">
<default-acl value="Profile$login$restAdmin:read,write,execute;
Profile$role$restUser:read"/>
<property name="property1">
<acl value="Profile$login$restAdmin:read,write"/>
</property>
<property name="property2" secure="false"/>
<method name="methodA">
<acl value="Profile$login$restAdmin:execute"/>
</method>
</property>
<method name="methodB" secure="false"/>
</resource>
<resource component="/some/other/Component" secure="false"/>
</resource>
</rest-security>
Methods which are overloaded and have different security requirements require a signature attribute,
available on the method tag. This attribute allows for a Java method signature that uniquely identifies the
method.
378
<default-acl value="Profile$role$restCommerceUser:read,write,execute"/>
</resource>
</rest-security>
379
380
The Legacy REST Web Services package includes two client libraries:
Java Client Library for Legacy REST (page 381)
ActionScript Client Library for Legacy REST (page 395)
These libraries make Legacy REST Web Services easier to use by hiding the complexity of creating connections,
assembling payloads for requests, and processing responses.
Creating Requests
It easiest to make most Legacy REST Web Services requests with the RestComponentHelper and
RestRepositoryHelper classes. These two classes simplify calling into the server by providing methods which
hide the complexity of assembling the data for the request. All the methods for both classes are static and each
returns a RestResult object and throws RestClientException. See the JavaDoc for more information about
each method.
atg.rest.client.RestComponentHelper
The methods of the RestComponentHelper class allow access to components, properties, and methods. Each
of the methods accepts a Map of parameters, which control the request. For more information and examples,
see Accessing Components with the Java Client Library (page 390).
381
atg.rest.client.RestRepositoryHelper Class
The methods of the RestRepositoryHelper class allow you to access repository items, execute RQL queries,
retrieve individual property values, set property values, create items, and remove items. Each of the methods
takes a Nucleus repository path and item descriptor name as its first two arguments, as well as a Map of
parameters, which control various aspects of the request. For more information and examples, see Accessing
Repository Items with the Java Client Library (page 392).
public static RestResult createItem(String pRepositoryPath, String
pItemDescriptorName, Map<String,Object> pParams, RestSession pSession)
Returns true if the repository item was successfully removed; otherwise, returns false.
public static RestResult getItem(String pRepositoryPath, String pItemDescriptorName,
String pItemId, Map<String,Object> pParams, RestSession pSession)
382
Returns the contents of the repository item. If any of the properties are references to other items, Collections,
arrays, or Maps, returns a REST URL that you can use to access the contents of the specific property. You can
create a raw REST request to access the data for the property. For more information, see Creating a Raw REST
Request (page 388).
public static RestResult getItems(String pRepositoryPath, String
pItemDescriptorName, Map<String,Object> pParams, RestSession pSession)
Returns a series of URLs, one for each item which is being returned. T to control the number of items returned,
the atg-rest-index and atg-rest-count parameters can be passed into the pParams argument.
public static RestResult executeRQLQuery(String pRepositoryPath, String
pItemDescriptorName, String pRQL, Map<String,Object> pParams, RestSession pSession)
Returns a series of URLs, one for each item which is being returned. To control the number of items returned,
the atg-rest-index and atg-rest-count parameters can be passed into the pParams argument.
Note: Do not include parameters in the RQL queries that you perform via the Legacy REST Web Services. Make
sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL
queries in the Repository Guide.
public static RestResult getPropertyValue(String pRepositoryPath, String
pItemDescriptorName, String pItemId, String pProperty, Map<String,Object> pParams,
RestSession pSession)
Returns the value of the requested property. If the property is a Collection, Map, array, or reference to another
repository item, returns a URL.
public static RestResult setPropertyValue(String pRepositoryPath, String
pItemDescriptorName, String pItemId, String pProperty, Object pValue,
Map<String,Object> pParams, RestSession pSession)
Note: You can perform multiple Legacy REST Web Services requests during an HTTP session. See information
about HTTP sessions and the Legacy REST Web Services server in Logging In (page 319).
383
Property
Description
Hostname
The name of the host which the session will or is connected to. Default is
localhost.
Port
The port number which the session will use. Default is 80.
Username
Password
Scheme
The scheme the session will use to connect. Default is HTTP expect for login
calls.
restContextRoot
The Web application context root for Legacy REST Web Services. Default is /
rest.
useInternalProfileForLogin
Tells the session object to login as an internal user instead of a profile user. You
will probably need to change this property after the RestSession object is
created and before login is called. When connecting to a server that can be
accessed only by internal users, this property must be set to true or the login
will fail.
useHttpsForLogin
Tells the session object to use the HTTPS scheme for login calls. Default is true.
httpsPort
The HTTPS port number which the session will use. Default is 443.
userId
The userId of the connected user. This value is set after logging in.
sessionId
The session ID of the current session. This value is set after logging in.
Encoding
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
384
import
import
import
import
atg.rest.client.RestClientException;
atg.rest.client.RestComponentHelper;
atg.rest.client.RestResult;
atg.rest.client.RestSession;
import java.io.IOException;
public class RestClientSample {
private String mUsername = null;
private String mPassword = null;
private String mHost = "localhost";
private int mPort = 80;
private RestSession mSession = null;
public RestClientSample() {}
protected void parseArguments(String[] pArgs) throws Exception {
for (int i = 0; i < pArgs.length; i++) {
String arg = pArgs[i];
if (arg.equals("-user"))
mUsername = pArgs[i+1];
else if (arg.equals("-password"))
mPassword = pArgs[i+1];
else if (arg.equals("-host"))
mHost = pArgs[i+1];
else if (arg.equals("-port"))
mPort = Integer.parseInt(pArgs[i+1]);
}
if (isBlank(mUsername))
throw new Exception("Must supply username");
if (isBlank(mPassword))
throw new Exception("Must supply password");
}
protected boolean isBlank(String pStr) {
return (pStr == null || pStr.length() == 0 || pStr.trim().length() == 0);
}
protected void println(String s) {
System.out.println(s);
385
}
protected void println(Throwable t) {
t.printStackTrace(System.out);
}
protected void execute() throws RestClientException {
mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword);
mSession.setUseHttpsForLogin(false);
try {
String loginStatus = mSession.login();
if(loginStatus == null || "null".equals(loginStatus)) {
mSession = null;
System.out.println("Login Failed");
}
else {
System.out.println("Login Successful");
}
}
catch (Throwable t) {
println(t);
}
finally {
try {
if(mSession != null) {
mSession.logout();
System.out.println("Logout Successful");
}
}
catch (RestClientException e) {
println(e);
}
}
}
/**
* @param args
*/
public static void main(String[] args) {
RestClientSample sample = new RestClientSample();
try {
sample.parseArguments(args);
sample.execute();
}
catch (Throwable t) {
sample.println(t);
}
}
}
386
Note: Starting a session without logging in will not give your REST client access to secured Oracle Commerce
Platform resources.
The following sample program starts a REST session using the startSession() method.
import atg.rest.client.RestClientException;
import atg.rest.client.RestSession;
public class RestClientStartSession {
// Use your own hostname and port.
private String mHost = "myserver";
private int mPort = 9876;
private RestSession mSession = null;
public RestClientStartSession() {}
protected void execute() throws RestClientException {
// Create a RestSession object. Use the constructor that
// takes only the REST server host and port.
mSession = RestSession.createSession(mHost, mPort);
// Invoke the startSession() method.
mSession.startSession();
// Verify that the session is started.
String sessionid = mSession.getSessionId();
System.out.println("The session ID is: " + sessionid);
// perform unsecured operations or login here
// forexample:
// mSession.login("myusername","mypassword")
}
public static void main(String[] args) {
RestClientStartSession sample = new RestClientStartSession();
try {
sample.execute();
}
catch (Throwable t) {
t.printStackTrace(System.out);
}
}
}
387
Another alternative is to simply output responseData, but this sample illustrates how you might use the
output. Similarly, if the output format was XML, you could create an XML document object using dom4j.
The finally block includes a call to close the result. Doing this will release the underlying connection
resources. If this call is omitted, the next call to the server using the same RestSession object will close the
result.
protected void execute() throws RestClientException {
RestResult result = null;
mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword);
mSession.setUseHttpsForLogin(false);
try {
mSession.login();
println("Login Successful");
result = RestComponentHelper.getComponent("/atg/dynamo/Configuration", null,
mSession);
String responseData = result.readInputStream();
if (responseData != null) {
JSONObject json = new JSONObject(responseData);
println(json.toString());
}
}
catch (Throwable t) {
println(t);
}
finally {
if (result != null)
result.close();
try {
mSession.logout();
println("Logout Successful");
}
catch (RestClientException e) {
println(e);
}
}
}
388
The following table describes the arguments for each version of this method.
Argument
Description
pURL
pParams
pArguments
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
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.
389
Other useful methods on the RestResult object are getResponseCode() and getResponseMessage().
These return the responses response code and message, respectively. For more information, see HTTP Status
Codes (page 57).
The Java client library uses the java.net.HttpURLConnection class to communicate with servers. To access
any functionality that the RestResult does not expose, call the getConnection() method to return the
underlying HttpURLConnection object.
When you are finished with the RestResult object, it is good practice to call the close() method. This
releases any resources that the HttpURLConnection might hold. If the connection is not closed, the next
request to the server will close the HttpURLConnection.
390
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.
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)
391
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.
392
The getItems() method retrieves multiple repository items of the same type in a single call. The following
code sample returns an array of URLs:
RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/
ProductCatalog", "product", params, session)
When a getItems() call returns many items, you can control the number of items returned with the atgrest-index and atg-rest-count parameters. The atg-rest-index parameter tells the server which item to
return first. The atg-rest-count parameter tells the server how many items past the index item to return.
In the following code sample, the first query, with an index of 0 and a count of 10, retrieves 10 items at a time.
The next query has an index of 10 and a count of 10, third, index of 20 and count of 10, and so on.
Map<String,String> params = new HashMap<String,String>();
params.put(RestConstants.COUNT, 10);
params.put(RestConstants.INDEX, 0);
RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/
ProductCatalog", "product", params, session);
params.put(RestConstants.INDEX, 10);
result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog",
"product", params, session);
params.put(RestConstants.INDEX, 20);
result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog",
"product", params, session);
Repository IDs
Each repository item has a unique identifier, called a repository ID. Depending on the repositorys configuration,
the repository ID might not be exposed as a property of the repository item. However, when a repository item
is returned with a REST RepositoryHelper method, you can reliably retrieve its repositoryID by getting the
value of the repositoryId property.
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/
393
394
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);
395
atg.rest.client.RestComponentHelper
The RestComponentHelper class simplifies Nucleus requests.
The RestComponentHelper methods are written in ActionScript as follows. For details about individual class
methods, refer to the Java Client Library for Legacy REST (page 381) section.
atg.rest.client.RestRepositoryHelper
The RestRepositoryHelper class simplifies repository requests.
The RestRepositoryHelper class methods are written in ActionScript as follows. For details about individual
class methods, refer to the Java Client Library for Legacy REST (page 381) section.
396
The following table describes the arguments for each of these methods.
Argument
Description
pMultiValueType
pComponentType
The class type of the component to instantiate for each element in the multivalve
type. For example, an array of integers in ActionScript could be converted to an
ArrayList of java.lang.Integer objects.
pFormat
The servers input format type. This can be retrieved from the session objects
inputFormat property.
pKeyType
pValueType
These arguments are similar to pComponentType and are absolute names of Java
classes to use for the key and value objects in the Java Map.
Similar to the Java client library, passing arguments to methods is generally straightforward. For primitive types,
just add them to the pArguments array.
397
For example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component",
"aMethod", ["/atg/commerce/catalog/ProductCatalog:product:prod12345"], null,
session, handleResult, handleFault)
To pass a reference to a Nucleus component, pass the Nucleus component path. For example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component",
"aMethod", ["/atg/dynamo/Configuration"], null, session, handleResult,
handleFault)
The following example is a call to a method which takes a repository item array and a GenericService array.
<programlisting>
var result:RestResultRestComponentHelper.executeMethod("/some/Component",
"aMethod",
[["/atg/commerce/catalog/ProductCatalog:product:prod12345",
"/atg/commerce/catalog/ProductCatalog:product:prod67890"],
["/atg/dynamo/Configuration","/atg/dynamo/Configuration"]],
null, session, handleResult, handleFault)
As mentioned above, arrays, ILists, and Objects must be converted before being passed to the server. The
following example demonstrate passing an array using the helper methods in the RestClientUtils class.
var arrayCollection:ArrayCollection = new ArrayCollection(["abc","def"]);
var result:RestResultRestComponentHelper.executeMethod("/some/Component",
"aMethod",
[RestClientUtils.convertIListToMultivalue(arrayCollection,
"java.util.ArrayList", "java.lang.String", RestConstants.JSON, session)],
null, session, handleResult, handleFault);
The following example, which calls executeMethod(), produces the same result as the previous example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component",
"aMethod", ["java.util.ArrayList:java.lang.String:[\"abc\",\"def\"]"], null,
session, handleResult, handleFault)
The following examples use the helper methods in the RestClientUtils class.
var result:RestResultRestComponentHelper.executeMethod("/some/Component",
"aMethod", [RestClientUtils.convertArrayToMultivalue(["abc","def"],
398
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()});
}
399
400
Index
A
ActivateScheduleActor, 256
ActiveCustomerProfileActor, 237
Actor
ActivateScheduleActor, Internal, 256
ActiveCustomerProfileActor, Internal, 237
AddressBookActor, Internal, 207
AddStoreCreditActor, Internal, 277
AvailablePricedShippingMethodsActor, Internal, 226
AvailableShippingMethodsActor, External, 133
CancelOrderActor, External, 149
CancelOrderActor, Internal, 242
CartModifierActor, External, 124
CartModifierActor, Internal, 216
ChangeCurrentCustomer, Internal, 206
ChangeOrderActor, Internal, 241
ChangePasswordActor, Internal, 180
ChangeSiteActor, Internal, 309
ClosenessQualifierActor, External, 154
ClosenessQualifierActor, Internal, 276
CommitOrderActor, External, 153
CommitOrderActor, Internal, 244
ConfirmLogoutActor, Internal, 180
ConfirmOrderActor, External, 150
ConfirmOrderActor, Internal, 245
CouponActor, External, 150
CouponActor, Internal, 232
CreateCreditCardActor, External, 140
CreateCreditCardActor, Internal, 233
CreateHardgoodShippingGroupActor, External, 133
CreateHardgoodShippingGroupActor, Internal, 226
CreditCardActor, Internal, 210
CSRCrossSellActor, Internal, 243
CSRGiftlistActor, Internal, 279
CSRGiftlistSearchActor, Internal, 286
CSRReturnsActor, Internal, 292
CSRScheduledOrderActor, Internal, 251
CSRScheduledOrderConfirmationActor, Internal, 258
CSRScheduledOrderInfoActor, Internal, 257
CustomerProfileActor, Internal, 201
CustomerSearchTreeQueryActor, Internal, 204
Index
401
Internal, 245
CouponActor
External, 150
Internal, 232
CreateCreditCardActor
External, 140
Internal, 233
CreateHardgoodShippingGroupActor
External, 133
Internal, 226
CreditCardActor, 210
CSRCrossSellActor, 243
CSRGiftlistActor, 279
CSRGiftlistSearchActor, 286
CSRReturnsActor, 292
CSRScheduledOrderActor, 251
CSRScheduledOrderConfirmationActor, 258
CSRScheduledOrderInfoActor, 257
cURL, 59
command components, 61
CustomerProfileActor, 201
CustomerSearchTreeQueryActor, 204
EndCallActor, 182
Endeca Search, 146, 267
EnvironmentChangeActor, 268
CancelOrderActor
External, 149
Internal, 242
CartModifierActor
External, 124
Internal, 216
catalog search, 146
ChangeCurrentCustomerActor, 206
ChangeOrderActor, 241
ChangePasswordActor, 180
ChangeSiteActor, 309
ClosenessQualifierActor
External, 154
Internal, 276
CommitOrderActor
External, 153
Internal, 244
ConfirmLogoutActor, 180
ConfirmOrderActor
External, 150
402
D
DeactivateScheduleActor, 256
DefaultLoginPageActor, 181
DuplicateAndSubmitActor , 255
DuplicateOrderActor, 249
dynSessConf, 70, 81, 87
F
filters
bean classes, in REST MVC, 101
defining in REST MVC, 102
Legacy REST, 362
modifying in REST MVC, 109
repository items, in REST MVC, 101
G
GiftlistActor, 164
GiftlistLookupActor
External, 169
Internal, 285
GiftlistSearchActor, 172
GiftListTableActor, 288
GlobalInfoActor, 307
Index
H
HTTP
requests, 57, 61
requests in Legacy REST, 317, 331
status codes, 57, 341
I
IsScheduledOrderTemplateActor, 260
J
JAX-RPC, 4, 9, 11
and WSDL, 8
JMS Messages, 16
Patch Bay, 16
type, 16
JSON
output in Legacy REST, 331
output in MVC REST, 58
L
LostPromotionsActor
External, 163
Internal, 278
M
ManualAdjustmentsActor, 263
message sink, 18
MessageToolsActor, 310
methods
executing with Legacy REST, 317
executing with REST MVC, 77
overloaded, specifying in REST MVC, 80
ModelMap, 71, 73
and filtering, 101
and hierarchy, 76, 99
and output elements, 92
ModifyOrderActor, 248
ModifyRefundValuesActor, 303
MoreCatalogsSearchActor, 267
O
OrderConfirmationActor
External, 154
Internal, 247
OrderLookupActor, 148
OrderNoteActor, 249
OrderSearchTreeQueryActor, 239
OriginalOrderNoteActor, 250
P
Patch Bay, 15, 17
Index
PaymentGroupActor
External, 135
Internal, 228
PriceListSearchActor, 271
PricingActor
External, 146
Internal, 269
ProductCatalogActor
External, 142
Internal, 265
ProfileActor, 116
PromotionsSearchActor, 276
PromotionWalletActor, 272
pushSite, 116
Q
QuoteActor, 250
R
repository
data binding Web Services, 21
delete item, 34
filtering in REST MVC, 108
items from XML, 29
items in Legacy REST, 354
match properties, 33
modify item, 32
RespondEmailActor, 304
REST, 55
cURL examples, 59
HTTP status codes, 57
output, 58
URLs, 56
URLs, adding parameters, 64
REST Legacy, 317
cURL example, 60
filtering, 362
framework, 56, 315
HTTP requests, 317
HTTP status codes, 341
output, default, 331
output, JSON, 332
output, XML, 332
repositories and, 354
security, 375
URLs, 317
URLs, adding parameters, 323
REST MVC, 67
cURL example, 60
examples, external user, 115
examples, internal users, 177
executing methods, 77
filtering, 101
403
framework, 56, 71
installing, 69
registering services, 69
schema, 73
security, 110
URLs, 73
URLS, error and success, 86
RestoreDefaultAgentOptionsActor, 181
ReturnsActor, 155
S
SaveOrderActor, 149
Scenario Actions, 16
Scenario Manager, 18
ScheduledOrderLookupActor, 260
ScheduledOrderTableActor, 262
security
Legacy REST, 375
REST MVC, 110
Web Services, 12
SendAndCloseTicketActor, 306
Service Endpoint Interface (SEI), 8
mapping to WSDL, 11
ServiceCustomerProfileActor, 237, 286
ServiceUIProfileActor, 200
servlet beans
filtering in REST MVC, 103
in Legacy REST, 353
retrieving in REST MVC, 84
session confirmation number, 70, 116, 178
disabing in Form actors, 87
disabling in Component actor, 81
SessionConfirmationActor
External, 116
Internal, 178
ShippingGroupActor
External, 129
Internal, 222
ShoppingCartActor
External, 121
Internal, 213
site context, external, 116
SiteGroupsActor, 308
SOAP, 4, 8, 9
and WSDL, 8
StartNewCallActor, 181
StateListActor, 175
StoreLocatorActor
External, 174
Internal, 289
SubmitModifiedOrderActor, 248
404
T
TicketActor, 184
TicketingActor, 183
TicketLookupActor, 194
TicketSearchActor, 198
TicketStatusDescriptionActor, 200
U
UpdateCreditCardActor
External, 141, 162
Internal, 235, 302
UpdateHardgoodShippingGroupActor
External, 134
Internal, 227
URLs, 56
adding Legacy REST parameters, 323
adding REST parameters, 64
and WSDL, 9
control parameters, 62
forwarding in REST MVC, 86
Legacy REST, 317
REST MVC, 73
success and error in REST MVC, 86
V
ViewAllPendingApprovalsActor, 289
ViewOrderActor, 241
W
Web Services
.Net, 44, 47
abstract data types, 5
cookies, 5, 37
DAS, 2
DCS, 2
deploying, 13
deserializer in .Net, 45, 49
deserializer in Java, 36, 42
DPS, 2
dynamic, 39, 41
exposing methods, 8
Java client, 35
JMS Messages, 15
JMS Type, 16
naming conflict, 5, 7
NucleusSecurityManager, 12
NucleusSecurityRepository, 13
primitive data types, 5, 8
Registry, 8, 11, 14
repository, for, 18
rollback a call, 35
scenario actions, 16
Index
security, 4, 12
serializer in .Net, 45, 49
serializer in Java, 36, 42
session sharing, 36, 45
static, 39, 39
wizard, 5
WSDL, 8, 10
XML file, 9
Web Services Description Language (WSDL) (see Also Web
Services)
mapping to SEI, 11
WebServicesGenerator, 6
X
XML
data binding, 21
data binding in REST MVC, 100
delete repository item, 34
generating schemas, 43
mapping in Web Services, 22
mapping Web Services DTD, 23
output in Legacy REST, 332
output, REST, 58
repository items, 29
schema mapping, 42
schemas, 27
validating, 32
Index
405
406
Index