Ws Frame Guide

Version 10.0.
2 Web Services and Integration Framework Guide
Oracle ATG One Main Street Cambridge, MA 02142 USA
Web Services and Integration Framework Guide Document Version

Doc10.0.2 INTFRAMEv1 04/15/2011
Copyright
Copyright 1997, 2011, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark licensed through X/Open Company, Ltd. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services. For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/us/corporate/accessibility/index.html. Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.
ATG Web Services and Integration Framework Guide
Contents
Part I: Creating and Using Web Services in the ATG Platform

ATG Web Services
9
10
Creating Custom Web Services

Overview of ATG Web Services Support JAX-RPC Automatic Generation of Web Services Session and Security Support Limitations Web Service Creation Wizard Using the Wizard Naming Restrictions Anatomy of a Web Service Service Endpoint Interface and Implementation Class WSDL Document web.xml File JAX-RPC Deployment Descriptor and Mapping Files Runtime Classes JSR 109 Compliant EAR File Web Service Security Security Components Creating and Editing Security Configurations Deploying Web Services Managing Web Services Registering Services
13
13 14 14 14 14 15 15 17 17 18 18 19 22 22 22 22 23 24 24 25 26
Creating JMS Web Services

Using the JMS Message Web Service Wizard Structure of a JMS Web Service Patch Bay Configuration
27
27 28 28
Creating Repository Web Services

Using the Repository Web Service Wizard Repository Web Service Limitations Modifying Repository Web Services RepositoryService Class
31
31 32 33 34
iii
Contents
Repository to XML Data Binding

Mapping Files and XML Schemas Mapping Files Managing Mapping Files for Repository Item Descriptors XML Schemas Managing Schemas and Mapping Files PropertyElementNameSeparator Item References Repository Operations Getting Repository Items Adding Repository Items Updating Repository Items Removing Repository Items
37
37 38 41 43 44 45 45 45 46 48 49 51
Accessing ATG Web Services from Java Clients

About ATG Web Services Security Transactions Sharing Sessions RepositoryItems Before You Begin Using a Java Client Writing a CookieContainer Class Calling ATG Web Services from a Java Client Creating a Call Using a Client Stub (Static) Creating a Call Using the Dynamic Invocation Interface (Dynamic) Creating a Serializer and Deserializer Creating a Mapping File Generating an XML Schema
53
53 53 54 54 54 55 55 58 58 60 61 62 62
Accessing ATG Web Services from .NET Clients

About Web Services in the ATG Platform Security Transactions Session Sharing Client Stubs Web Services that Access RepositoryItems Before You Begin Using a .NET Client Installing ATGWS.dll Calling ATG Web Services from a .NET Client Accessing an ATG Web Service Accessing a Custom ATG Web Service Sample Web Service Calls Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems RepositoryItem Class Property Class RepositoryItemRef Class
65
65 65 66 66 66 66 67 67 68 68 68 69 70 72 73 74
iv
Contents
74 75 75 76
Complex Type Class NoSuchPropertyException Class RepositoryItemSerializer Class RepositoryItemSerializationException Class
Part II: Integration Framework

Integrators and Adapters
77
77
Using the Integration Repository

Architecture Integration Approaches Remote Only Remote then Local Local then Remote Local Only Setting Up an Integration Repository Defining an Integration Repository Integration Repository APIs IntegrationRepository IntegrationRepositoryItemDescriptor IntegrationRepositoryItem ChangedPropertyBean atg.repository.databinding.MappingRepositoryItem IntegrationRepositoryView Command Operations executeQuery getItem updateItem addItem removeItem Mapping Persistent Caching Cleaning up the Persistent Cache Configuration Examples Configuring the Remote-Only Model Configuring the Remote-then-Local Model Configuring the Local-then-Remote Model Integration Repository Definition File integration-repository-template tag header tag item-descriptor tag item-descriptor Child Tags integration-repository Document Type Definition
79
79 80 80 81 81 82 82 83 84 85 87 88 88 88 88 90 90 91 91 92 93 93 94 95 95 95 97 98 98 99 99 99 100 103
Remote Procedure Calls

RPC API Architecture
107
107
v
Contents
Command Interface CommandHandler Interface CommandResult Class Implementing the RPC API Exception Handling Executing Commands in Pages
107 108 109 109 110 110
Part III: ATG Platform REST Web Services 9 Using REST Web Services
Starting the REST module HTTP Requests REST Web Services URLs Client Software HTTP Methods Handling POST Requests as Other Methods Logging In Handling Session Identifiers Logging In as an External User Logging In as an Internal User Logging Out Control Parameters Control Parameter Reference Functional Parameters Positional Parameters URL Parameters Message Body Parameters Setting the Content-Type Value XML Parameter Markup JSON Parameter Markup URL Query String Parameter Markup Input Values Primitive Values in Input Multiple Values in Input HTTP Status Codes Returned Data Choosing Output Markup JSON Output XML Output Identifying a Response Multiple Values in Output Return Depth Errors and Exceptions Problems Performing Operations Problems Processing a Request
113 115
116 116 116 118 119 120 120 120 121 122 124 125 125 127 127 128 128 129 130 130 131 131 131 131 134 134 134 135 136 137 138 143 144 144 145
vi
Contents
149
149 150
10 Working with Component Properties

Getting Component Properties Setting Component Properties
11 Invoking Component Methods 12 Invoking Form Handlers

Submitting Form Values Returning Form Handler Exceptions Returning Form Handler Properties Form Value Priority
153 155
156 157 157 158
13 Working with Repositories

Listing Repository Items Retrieving a Repository Item Retrieving a Specific Property Performing RQL Queries Adding a Repository Item Transient Items Setting Repository Item Properties Deleting a Repository Item
159
159 160 162 163 164 166 166 168
14 Property Filtering
Default Filtering Specifying the Filter Depth Filtering for One Request Property Aliasing
171
171 174 174 176
15 Configuring the REST Server

/atg/rest/Configuration defaultOutputCustomizer maxDepthAllowed /atg/rest/processor/BeanProcessor returnFormHandlerExceptionsByDefault returnFormHandlerPropertiesByDefault /atg/rest/output/JSONOutputCustomizer showRestPaths JSON /atg/rest/output/XMLOutputCustomizer showRestPaths XML /atg/rest/processor/RepositoryProcessor acceptJSONInput appendMultiValuesByDefault /atg/rest/processor/RestSecurityProcessor allowAccessForUnsecuredRepository
177
177 177 177 177 177 178 178 178 178 178 179 179 179 179 179
vii
Contents
16 Security for REST Web Services

Security Overview Logging In and Session IDs Nucleus Component Granularity Quick Setup for Testing Global Security Component Security Property and Method Security Repository Security Securing Groups of Components
181
181 181 181 182 182 183 183 184 184
17 ATG Client Libraries

Java Client Library Creating Requests Creating a RestSession Object Logging in and Logging Out with the Java Client Library 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 ActionScript Client Library atg.rest.client.RestComponentHelper atg.rest.client.RestRepositoryHelper Calling Methods with ActionScript Formatting Input with ActionScript
187
187 187 190 191 193 194 195 196 197 199 202 202 203 204 206
Index
208
viii
Contents
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 ATG 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 ATG 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 ATG 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 chapters in this section discuss how to create Web Services in the ATG platform, and how to write Java and .NET clients that call these services: Creating Custom Web Services Creating JMS Web Services Creating Repository Web Services Repository to XML Data Binding Accessing ATG Web Services from Java Clients Accessing ATG Web Services from .NET Clients
9

ATG Web Services
In addition to any Web Services you create, the ATG platform includes a number of prepackaged Web Services that you can call from Java and .NET clients. These services are packaged in three separate application modules. You can include any of these services in an assembled EAR file by including the module that contains the desired services. For example, to include the prepackaged Commerce Web Services, specify the DCS.WebServices module when you assemble your application. The following table summarizes these Web Services:
Application Module
DAS.WebServices
Web Application Generic Repository Services
Web Services
- getRepositoryItem - performRQLQuery - performRQLCountQuery
For more information about these Web Services, see the ATG Repository Guide.
DPS.WebServices
User Session
- loginUser - logoutUser - getProfileId - setLocale - setContactInfo - setPassword - getProfile - createUser - updateUser - getPasswordHashKey - getPasswordHashAlgorithm - canClientEncryptPasswords - executeRepositoryTargeter
For more information about these Web Services, see the ATG Personalization Programming Guide
Messaging
- sendPageVisit - sendClickThrough
10
DCS.WebServices
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
For more information about these Web Services, see ATG Commerce Programming Guide.
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
11
12
1 Creating Custom Web Services
The ATG platform provides infrastructure and tools that enable you to expose a wide range of ATG functionality as Web Services. There are three kinds of Web Services you can create that expose ATG functionality: Web Services that invoke methods on Nucleus components. Web Services that send JMS messages through Patch Bay. Web Services that perform operations on repository items.
This chapter describes the infrastructure for creating these services. It focuses on Web Services that invoke Nucleus methods, but most of what is described here applies to all three types of services. For information specific to Web Services that send JMS messages, see the Creating JMS Web Services chapter. For information specific to Web Services that perform repository operations, see the Creating Repository Web Services chapter. This chapter includes the following sections: Overview of ATG Web Services Support Web Service Creation Wizard Anatomy of a Web Service Web Service Security Deploying Web Services Managing Web Services
Overview of ATG Web Services Support

This section describes key aspects of ATG Web Services support: JAX-RPC Automatic generation of Web Services Session and security support Limitations
13
1 - Creating Custom Web Services

JAX-RPC
The Web Services support in the ATG 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 ATG platform uses Oracles reference implementation of JAX-RPC. Parts of this reference implementation are used to generate Web Services, and other parts of it handle the processing of SOAP messages when a Web Service is called.
Automatic Generation of Web Services

Creating a Web Service by hand can be a laborious process, due to the large number of Java and XML files you must create and package. The ATG platform automates this process through the Web Service Creation Wizard in the Dynamo Administration UI. You select the type of service you want to generate, and the wizard takes you through a series of screens where you specify the necessary information. You then click a button, and the wizard automatically generates the necessary classes, WSDL documents, and deployment descriptors, and packages them in EAR and WAR files.
Session and Security Support

When you create a Web Service, you specify whether it should be executed within the context of an HTTP session. Associating Web Services with a session enables an application to maintain state across Web Service calls and to use login information for security purposes. To enable multiple Web Services to execute within the same session, a client application must pass a session cookie between calls. Some Web Services frameworks, such as 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 ATG Web Services from Java Clients chapter. For more information about using sessions with .NET clients, see the Accessing ATG Web Services from .NET Clients chapter.
Limitations
You can create Web Services from most Nucleus methods, both from components ATG provides and components that you write. There are, however, some methods that cannot be exposed as valid Web Services. The Web Service Creation Wizard will 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
14
custom code), or else subclass the methods class (if it is a class provided by ATG) and overload the method with a version that uses primitives. In addition, you cannot create a Web Service from a method that has the same name and signature as any of the methods of atg.webservice.ManagedComponentProperties or java.lang.Object. Attempting to do so results in a naming conflict, because the service implementation class of each Web Service subclasses atg.webservice.ManagedComponentProperties, which subclasses java.lang.Object. Note that the wizard does not prevent you from selecting these methods, but when you try to generate a Web Service, an exception is thrown and the service generation fails.
Web Service Creation Wizard

The process of creating Web Services is automated by the Web Service Creation Wizard in the Dynamo Administration UI. This wizard guides you through the steps of selecting a Nucleus component and method, specifying input parameters and other settings; it then automatically creates the Web Service by performing the following steps: Create the service endpoint interface that specifies the method to be exposed. Create the service endpoint class that implements the service endpoint interface and is responsible for handing incoming SOAP requests. Create the WSDL document that describes the resources required by the service endpoint class, as well as its inputs and outputs. Create the web.xml file for the Web application that the service is a part of. Create the JAX-RPC deployment descriptor (webservices.xml) and mapping file. Build the runtime classes. Package these elements in a JSR 109 compliant EAR file.
These steps are described in more detail in the Anatomy of a Web Service section. The wizard uses the component /atg/webservice/WebServiceGenerator to perform the actual work of generating the service. This component, which is of class atg.webservice.WebServiceGeneratorImpl, performs all of the operations listed above, either through its own methods or through other components it refers to.
Using the Wizard

The top-level page of the Dynamo Administration UI includes a Web Service Administration link. This link takes you to the Web Service Administration page, which has three links for working with Web Services: Web Service Registry Takes you to a page for viewing and managing currently loaded Web Services. The Web Services registry is discussed in the section Managing Web Services. Web Service Security Manager Enables you to create and edit Web Service security configurations. These security configurations can be used to define which users can
15
access specific Web Services. When you create a Web Service, you have the option of associating a security configuration with the service. Security configurations are discussed in the section Web Service Security. Web Service Creation Wizard Takes you to a page with links for creating each of the three kinds of Web Services (Component Method Web Service, JMS Message Web Service, Repository Web Service).
To create a Web Service that invokes a method on a Nucleus component, starting from the Web Service Administration page: 1. 2. 3. Click the Web Service Creation Wizard link. This takes you to a page titled Select Type, where you can select the type of Web Service to create. Click the Component Method Web Service link. This takes you to the Select Nucleus Component page. On the Select Nucleus Component page, specify the pathname of the Nucleus component you want to create the Web Service from. You can either enter the pathname directly in the field at the top of the page and then click the Next button, or you can use the component browser below it to navigate to the component and select it. On the Select A Method page, select the method you want to expose as a Web Service. If the method requires any input parameters, the Set Parameter Names page provides you with fields for specifying the names of these parameters. The names you specify are used for the parameters of the Web Service call, and can be anything you like. When the Web Service is called, the service passes the values of these parameters to the parameters of the exposed Nucleus method. There is thus a one-to-one correspondence between the parameters of the Web Service call and the parameters of the underlying Nucleus methods. 6. The next two pages are titled EAR Name & Servlet Settings and Enterprise and Web Application Settings. When the wizard creates a Web Service, it packages it in a WAR file, which is in turn packaged in an EAR file. It is possible to have any number of services in a single Web application (WAR file), and any number of Web applications in a single Enterprise application (EAR file). This flexibility gives you a good deal of control over how you deploy your Web Services. For each new Web Service, the wizard can do any of the following: Create a new EAR file for the service, and put it in a WAR file within the EAR file. Use an existing EAR file, and put the service in a new WAR file within it. Put the service in an existing WAR file within an existing EAR file. To add a Web Service to an existing EAR file, you specify that file as the EAR file name on the EAR Name & Servlet Settings page. The Web Application Settings page then gives you the choice of creating a new Web application for the service, or adding the service to an existing Web application. The wizard also gives you the option of specifying the host name and port number for a Web Service, or of leaving these fields blank. If you leave the fields blank, the values are dynamically assigned at runtime from the URL used for the WSDL file request.
4. 5.
16
7.
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 for information about security configurations for Web Services.
8.
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 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 will simply overwrite 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 youll need to change the value when you run the wizard.) It will then be possible to differentiate calls to the two services based on their context roots.
Anatomy of a Web Service

As mentioned above, the Web Service Creation Wizard automatically performs a number of tasks, greatly simplifying the creation of Web Services from Nucleus components. The wizard enables you to simply create Web Services and begin using them, without needing to understand all of their underpinnings. However, in some cases you may need to troubleshoot or make changes to your Web Services, so it is helpful to have some familiarity with their form and packaging. This section discusses the various pieces that make up a Web Service, including: service endpoint interface and implementation class WSDL document
17

web.xml file
JAX-RPC deployment descriptor (webservices.xml) and mapping file runtime classes JSR 109 compliant EAR file
Note that the business logic of the Web Service is actually contained in the method of the Nucleus component that is being exposed. The Web Service handles only the RPC infrastructure, and passes the actual processing to the Nucleus component.
Service Endpoint Interface and Implementation Class

The service endpoint interface (SEI) is a Java interface class that defines the methods to be exposed as a Web Service. This interface must extend the java.rmi.Remote interface and each method must throw java.rmi.RemoteException. The SEI for any Web Service generated by the ATG platform has a single method, corresponding to the Nucleus method being exposed. The service implementation class (also referred to as the service bean) implements the service endpoint interface and handles the actual servicing of incoming SOAP requests. In addition, service implementation classes generated by the ATG platform implement the interface javax.xml.rpc.server.ServiceLifecyle, and extend the atg.webservice.ManagedComponentProperties class, which registers services with the ATG platform Web Service Registry. The Web Service Registry is discussed in the Managing Web Services section. The service endpoint interface and implementation class are generated by the
/atg/webservice/WebServiceGenerator component. The names for these classes are based on the
name of the Nucleus method being exposed. For instance, if the Nucleus method is getOrderStatus, the service endpoint interface is named GetOrderStatusSEI, and the implementation class is named GetOrderStatusSEIImpl.
WSDL Document
Web Services Description Language (WSDL) is an XML language for describing Web Services in a platformindependent way. A WSDL document describes a Web Services methods by specifying the locations of the resources they use and defining the methods inputs and outputs. (A WSDL document for a Web Service generated by the ATG 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:
18
<message name="getOrderStatusInput"> <part name="in0" type="xsd:string"> </message>
Each non-primitive input or output requires its own WSDL document that is imported by the primary WSDL document. Import statements similar to the following are included in the primary WSDL document when the Web Service is created using the Dynamo Administration UI:
<import location="atg.commerce.order.status.wsdl" namespace="http://www.atg.com/atg.commerce.order.status"/>
The location specified is relative to the primary WSDL document. Some Web Service clients are able to interpret relative locations, but others require fully qualified URLs. To work with these clients, when the ATG 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. 2. At runtime, JAXRPCServlet updates the SOAP address in the WSDL document to include the domain host name and port number. When WSDLFinderServlet detects a WSDL request, WSDLImportFilter appends the domain name and port number (from the SOAP address provided by JAXRPCServlet) and the context path (by calling request.getContextPath() on the Dynamo request) to the location value in the import statement. The resulting import statement looks similar to this:
<import location= "http://myhost:7881/catalog/atg.commerce.order.status.wsdl" namespace="http://www.atg.com/atg.commerce.order.status"/>
The WSDLFinderServlet and WSDLImportFilter classes are declared in the web.xml file for the Web application that the Web Service is a part of, as discussed in the next section. For more information about request handling, see the ATG Programming Guide.
web.xml File
The web.xml file is the standard deployment descriptor for the Web application that the Web Service is a part of. It declares the filters and servlets used by the service. On the ATG 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>
19

<init-param> </init-param> </servlet> ... <servlet-mapping>
<param-name>configuration.file</param-name> <param-value>WEB-INF/wsconfig/getOrderStatus_Config.properties</param-value>
<servlet-name>getOrderStatus</servlet-name> <url-pattern>/getOrderStatus/*</url-pattern> </servlet-mapping>
When a call to the getOrderStatus Web Service is sent to the ATG platform, the JAXRPCServlet receives the request and dispatches it based on the information in the file that the configuration.file parameter points to. This configuration file is included in the WAR file, and looks similar to this:
port0.wsdl.serviceName=GetOrderStatusSEIService port0.tie=webservices.GetOrderStatusSEI_Tie wsdl.transform=true port0.name=getOrderStatus portcount=1 wsdl.location=WEB-INF/getOrderStatus.wsdl port0.servant=webservices.GetOrderStatusSEIImpl port0.wsdl.targetNamespace=http\://www.atg.com/webservices port0.wsdl.portName=GetOrderStatusSEIPort
Note that the port0.servant property is set to the name of the service implementation class. This property designates the class that JAXRPCServlet dispatches the SOAP request to.
Handling Imported WSDL Documents

As discussed in the WSDL Document section, there are two resources that assist in handling WSDL requests. These resources are declared in the web.xml file:
WSDLImportFilter, which is a filter of class atg.webservice.WSDLImportFilter,
is mapped to a parent directory that has subdirectories holding WSDL documents.

WSDLFinder, which is a servlet of class atg.webservice.WSDLFinderServlet, should be defined and mapped to each path that will lead to a WSDL document.
For example:
<filter> <filter-name>WSDLImportFilter</filter-name> <filter-class>atg.webservice.WSDLImportFilter</filter-class> </filter> ... <filter-mapping> <filter-name>WSDLImportFilter</filter-name>
20
<url-pattern>/getOrderStatus/*</url-pattern> </filter-mapping> ... <servlet> <servlet-name>WSDLFinder</servlet-name> <display-name>WSDLFinder</display-name> <description>Used to lookup imported wsdl files.</description> <servlet-class>atg.webservice.WSDLFinderServlet</servlet-class> </servlet> ... <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.order.status.wsdl</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.security.wsdl</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>WSDLFinder</servlet-name> <url-pattern>atg.commerce.wsdl</url-pattern> </servlet-mapping>
Web Service Registrar

To register Web Services with the Web Services Registry, the web.xml file declares the WebServiceRegistrar servlet, and sets it to load on startup:
<servlet> <servlet-name>WebServiceRegistrar</servlet-name> <display-name>WebServiceRegistrar</display-name> <description>ATG WebServiceRegistrar for registering servlet web-services.</description> <servlet-class>atg.webservice.WebServiceRegistrar</servlet-class> <load-on-startup>1</load-on-startup> </servlet>
For more information about the Web Services Registry, see Managing Web Services.
Other Elements of web.xml

The web.xml file may declare certain additional elements: the servlet atg.nucleus.servlet.NucleusServlet, which runs Nucleus as a servlet within a Web application the filter atg.filter.dspjsp.PageFilter, which invokes the DAF requesthandling pipeline
21
the context parameter atg.session.parentContextName; its value is set to /dyn, which enables the Web Services to share information with the atg_bootstrap.war application
JAX-RPC Deployment Descriptor and Mapping Files

The JAX-RPC deployment descriptor, webservices.xml, provides metadata (such as names and descriptions of the SEIs, service beans, and WSDL documents) about all of the Web Services in a given Web application. The mapping file defines the association between a WSDL file and an SEI and implementation class, by mapping namespaces to Java packages. This mapping is used when serializing and deserializing XML files. There is a separate JAX-RPC mapping file for each Web Service, and the name of each file reflects the method the service is based on. For example, if the method is getOrderStatus, the mapping file for the Web Services is named getOrderStatusMapping.xml.
Runtime Classes
The runtime classes are generated using the Oracle JAX-RPC reference implementation. These classes include: the tie class that JAXRPCServlet invokes the method on, and which in turn invokes the method on the service implementation class classes for handling serializing and deserializing SOAP requests and responses
JSR 109 Compliant EAR File

The JSR 109 Java specification includes information about how a Web Service should be packaged within an EAR file. The wizard combines all the generated files (class files, web.xml, WSDL document, webservices.xml, and JAX-RPC mapping file) into a WAR file, which is then added to a JSR 109 compliant EAR file.
Web Service Security

When you create a Web Service, you have the option of applying security constraints so that only approved clients (those with administrator privileges, for example) can execute it. You specify the security constraints using a security configuration, which is a repository item that stores information that controls access to the Web Service. You can create any number of different security configurations using the Web Services Administration UI, and you can apply a security configuration to any number of Web Services. A security configuration has a corresponding security policy component, plus an optional ACL. A security configuration is identified by its functional name, which is a property of the repository item that maps the security configuration to a security component and ACL.
22
This section describes the main components involved in securing Web Service methods, as well as how to create security configurations through the Web Services Administration UI. For a broader discussion of the ATG security API, see the Managing Access Control chapter in the ATG Programming Guide.
Security Components
There are two primary components involved in securing a Web Service method:
/atg/webservice/security/NucleusSecurityManager (an instance of atg.webservice.NucleusSecurityManager) uses the security configuration
associated with the Web Service to apply the corresponding security policy and ACL, to determine whether to grant or deny access.
/atg/webservice/security/NucleusSecurityRepository (an instance of atg.adapter.gsa.GSARepository) stores the Web Service security configurations used by the NucleusSecurityManager.
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 true (grant access). This setting 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 ATG platform, the defaultGrantAccess property is set to false. Note, however, that this means that each of your Web Services must have an associated security configuration, because any call to a service without a security configuration will fail. For information about enabling liveconfig settings, see the ATG Installation and Configuration Guide.
NucleusSecurityRepository
Web Service security configurations are stored in the NucleusSecurityRepository. This repository includes a single item descriptor called nucleusSecurity, which has properties called functionalName, policy, and ACL. The NucleusSecurityManager parses the items in this repository at startup time.
23
The Web Services Administration interface provides an easy way to add new security configurations to this repository. See the next section for details.
Creating and Editing Security Configurations

The Web Services Administration page in the Dynamo Administration UI includes a Web Service Security Manager link that takes you to a page that where you can view and edit the security configurations stored in the NucleusSecurityRepository, or create new security configurations. Follow these steps to create a new security configuration: 1. 2. 3. Click the Create New link. On the Create Security Configuration page, enter a name for the security configuration in the Functional Name field, and click Create New button. On the Edit Web Service Security Configuration page, click the Add buttons to add users, roles, and organizations to the security configuration. You can change the security policy (from the /atg/dynamo/security/SecurityPolicy default) if necessary.
The new security configuration appears on the main Web Service Security Configurations page. If you need to make changes to it, click the Edit link to open the Edit Web Service Security Configuration page. Note that you cannot change the functional name.
Deploying Web Services

When you create a Web Service, the wizard places the EAR file in the <ATG10dir>/home directory. The Web Service is not ready to run, however, because it does not include the necessary Nucleus classes. In order to run the Web Service, these additional steps are necessary: 1. 2. Use the runAssembler command to assemble a Nucleus-based application, using the
-add-ear-file flag to incorporate the contents of the Web Services EAR file.
Deploy the assembled EAR file on your application server, and start up the application.
For example, if your Web Services EAR file is called WS.ear, you might use a command like this to assemble a Nucleus-based application named MyApp.ear:
runAssembler -add-ear-file WS.ear MyApp.ear -m MyApp DSS
If you make any subsequent changes to the Web Service, you must reassemble and redeploy the application for the changes to take effect. Note that in addition to any Web Services you create, the ATG platform includes a number of prepackaged Web Services. These services are packaged in three separate application modules. You can include any of these services in an assembled EAR file by including the module that contains the desired services. For example, to include the prepackaged Commerce Web Services, specify the DCS.WebServices module when you assemble your application.
24
For more information about the runAssembler command, see the ATG Programming Guide. For information about deploying EAR files, see the documentation from your application server vendor.
Managing Web Services

The Dynamo Administration UI provides a facility for managing the Web Services deployed on your server. To access this facility, open the top-level page of the Dynamo Administration UI and click the Web Service Administration link. On the Web Service Administration page, click the Web Service Registry link. This takes you to the page for the /atg/webservice/WebServiceRegistry component, which stores information about the available Web Services. For example, if the Web Services included with ATG Commerce are running on your Dynamo server, the top of the page will look similar to this:
The Service Info indicates that there are six Web applications running that include Web Services. You can get more information about the services in a Web application by clicking the details link next to the applications name. For example, if you click on the link for the Pricing application, the Service Info looks like this:
25
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 Web Service Registrar section.
26
2 Creating JMS Web Services
In addition to Web Services that call Nucleus methods, the ATG platform enables you to create Web Services that send JMS messages through Patch Bay. Many events in the ATG platform are triggered by JMS messages, so by calling a Web Service that sends a JMS message, a client can start execution of various services and processes. In particular, scenario actions are triggered by JMS messages, so you can use Web Service calls to invoke scenario actions remotely. For example, suppose a new user registers in some application, which invokes a Web Service that sends the registration information to the ATG 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 email message to the new user. This chapter discusses how to create Web Services that send JMS messages, and how to configure components to listen for these messages. For more information about JMS and Patch Bay, see the Dynamo Message System chapter of the ATG Programming Guide.
Using the JMS Message Web Service Wizard

To create a Web Service that sends a JMS message, you use the Web Service Creation Wizard, just as you do for Web Services that invoke Nucleus methods. On the first screen of the wizard, however, you click the JMS Message Web Service link (rather than the Component Method Web Service link). In this version of the wizard, you do not select a Nucleus component and method; instead, the key selections are the message type and the Patch Bay port name to use. The message type is the JMSType value for the message. This is a String, stored in the messages header, that identifies the kind of message it is. For example, a message of JMSType atg.dps.PageVisit is sent when a site visitor displays a page. For the port name, the wizard gives you two options, IndividualEvents and GlobalEvents. These are the standard ports where the Scenario Manager listens for scenario events. The names of the classes generated by the wizard are based on the JMS message type of the message. For example, if you create a Web Service that sends a message whose JMSType is atg.dps.PageVisit, the service implementation interface is named SendPageVisitSEI, and the service implementation class is named SendPageVisitSEIImpl.
27
2 - Creating JMS Web Services
Structure of a JMS Web Service

JMS Web Services generated by the wizard are similar to Web Services that call Nucleus methods. JMS services expose a Nucleus method, but it is always the receiveObjectMessage() method of the component /atg/dynamo/messaging/MessageImporter. This method receives the message object and forwards it into Patch Bay. The receiveObjectMessage() method takes three parameters: the message object a String indicating the JMSType of the message a String indicating the Patch Bay port name to use
The Web Service call itself takes only a single argument, the message object. The JMSType and port name are hard-coded when you generate the Web Service, and the service implementation class passes them (along with the message object supplied by the client) to the receiveObjectMessage() method. This simplifies the clients task, because it does not need to be aware of either the JMSType or the port name. For example, a Web Service that sends a JMS message when a user views a page would be called like this:
public void sendPageVisit(atg.userprofiling.dms.PageVisitMessage a);
The service implementation class then calls the receiveObjectMessage() method like this:
messageImporter.receiveObjectMessage(a, "atg.dps.PageVisit", "IndividualEvents");
For information about calling Web Services that send JMS messages from Java clients, see the Accessing ATG Web Services from Java Clients chapter. (Note that you cannot use the dynamic process described in that chapter for calling these Web Services.) For information about calling Web Services that send JMS messages from .NET clients, see the Accessing ATG Web Services from .NET Clients chapter.
Patch Bay Configuration

The /atg/dynamo/messaging/MessageImporter component, whose receiveObjectMessage() method is invoked by JMS Web Services, is a Patch Bay message source. When a Web Service invokes the method, the message passed to that method is sent either to the destination patchbay:/sqldms/MessageImporter/IndividualEvents or to patchbay:/sqldms/MessageImporter/CollectiveEvents, depending on the message type. The standard Patch Bay configuration file, /atg/dynamo/messaging/dynamoMessagingSystem.xml, includes the necessary declarations for the message source and destinations:
<message-source> <nucleus-name>
28
/atg/dynamo/messaging/MessageImporter </nucleus-name> <output-port> <port-name> IndividualEvents </port-name> <output-destination> <destination-name> patchbay:/sqldms/MessageImporter/IndividualEvents </destination-name> <destination-type> Topic </destination-type> </output-destination> </output-port> <output-port> <port-name> GlobalEvents </port-name> <output-destination> <destination-name> patchbay:/sqldms/MessageImporter/CollectiveEvents </destination-name> <destination-type> Queue </destination-type> </output-destination> </output-port> </message-source>
The Scenario Manager is a message sink configured to receive messages from these destinations. This configuration occurs in two places: In the standard Patch Bay configuration file, the Scenario Manager is configured to receive individual scenario events from the destination patchbay:/sqldms/MessageImporter/IndividualEvents. In the /atg/dynamo/messaging/dynamoMessagingSystemDSSGlobal.xml file, the Scenario Manager is configured to receive global scenario events from the destination patchbay:/sqldms/MessageImporter/CollectiveEvents.
You can configure other message sinks to receive messages from the
patchbay:/sqldms/MessageImporter/IndividualEvents destination by declaring them in the dynamoMessagingSystem.xml file. Note, however, that you cannot configure other sinks to receive messages from patchbay:/sqldms/MessageImporter/CollectiveEvents. This destination is a queue, used by global Scenario Managers only; adding sinks to this destination may interfere with the global Scenario Managers receiving messages. If you want another message sink to receive these messages, configure an additional destination for MessageImporter to send global scenario events to, and configure your sink to listen to that destination instead.
29
30
3 Creating Repository Web Services
The ATG Dynamo Administration interface provides an easy, browser-based way to create Web Services based on repository items. This Repository Web Service wizard is part of the Web Service Administration user interface, which is introduced in the Web Service Creation Wizard section of the Creating Custom Web Services chapter. You can use the Repository Web Service wizard to create Web Services that add, remove, update, or get a complete repository item, or a single property of a repository item.
Using the Repository Web Service Wizard

To use the Repository Web Service wizard to create a repository Web Service: 1. 2. Open the ATG Dynamo Administration interface and navigate to the Web Service Administration > Web Service Creation Wizard > Repository Web Service page. Identify the repository component that the Web Service should access. You can do this in one of two ways. The Create Repository Web Service page displays a text field in which you can enter the Nucleus address of the repository component and click the Submit button. The Create Repository Web Service page also displays a list of all repository components that are registered in the initialRepositories property of the /atg/registry/ContentRepositories component. You can select a repository component by clicking the link with the Nucleus address of the repository component. The next page, with the heading Select item descriptor, displays all of the item descriptors in the repository component you selected. Click the link for the item descriptor you want to expose in your Web Service. The next page, with the heading Select Method, displays the methods that are available for the item descriptor you selected. For example, if the item descriptor is mutable, the following methods are available:
add remove update get
3.
4.
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.
31
3 - Creating Repository Web Services

5.
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 for more information. Click the name of the method you want to expose in your Web Service. 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 chapter for information about security configurations for Web Services. 8. The Create EAR File page displays the parameter values you have selected for your Web Service. Review them, then click the Create EAR File button to create the Web Service. The Web Service is created in an EAR file. You will find the EAR file in the
<ATG10dir>/home directory, with the name you selected in step 4.
To use the new Web Service, you need to deploy it. See Deploying Web Services in the Creating Web Services chapter.
Repository Web Service Limitations

Because of the limitations inherent in Web Services, repository items must generally be passed in XML form. See the Repository to XML Data Binding chapter for information about transforming repository items into XML files and vice versa. In particular, you should bear in mind the following restrictions when you are creating repository Web Services:
32
get/setPropertyValue
1. 2. 3. 4. Collection properties may not be set or gotten as a whole. Only elements of the collection may be set.
RepositoryItem properties are set or gotten as Strings in XML form
There is no type of service that can get or set sub-properties. You must act upon the actual RepositoryItem you wish to read from or write to. You cannot get or remove elements from a set or list. This is because in order to remove elements from either, you need to provide the object to remove (or index, see below), and a Web Service cannot guarantee that that object is of a type that can be transformed from XML into a Java object. You cannot get or set a property of a type that corresponds to a Java primitive. For example, you cannot get or set a java.lang.Integer or a java.lang.Boolean. You cannot get or set a property of a non-simple type, other than atg.repository.RepositoryItem. This includes types such as java.util.Timestamp and java.sql.Date. Note, however, that if you retrieve a Date property, a java.util.Calendar will be returned. You cannot get a property that is not readable, or set a property that is not writable.
5. 6.
7.
addItem
The item to be added must be supplied in XML form.
updateItem
1. 2. The item to be updated must be supplied in XML form. By default, when a repository item is passed into the Web Service, the existing RepositoryItem is found by matching repository IDs. We determine the value of the repository ID from the top-level XML element in the instance document, and then find a repository item with a matching ID.
removeItem
Users must pass in only the repository ID of the item to be removed.
Modifying Repository Web Services

Note that when you create a repository Web Service using the Web Service Creation Wizard, the component path of the repository, the item descriptor name and, if applicable, the property name, are all hardcoded in the generated Web Service. If any of these variables is changed, the Web Service will need to be regenerated. Please note that the repository name is not taken into consideration when naming the Web Service. Only the item descriptor name and, if applicable, property name, is used to name a service. This means that if you are generating Web Services for two or more repositories with the same item descriptor names, you should consider placing them into different WAR files, or giving them different servlet URLs.
33
RepositoryService Class
The atg.repository.RepositoryService class contains many methods that perform basic Repository operations, independent of any particular repository implementation or instance. Such operations include getting, adding, removing and updating a repository item, setting and getting properties of repository items, and performing queries for repository items using RQL. Using the Web Service generator, you can directly make some of these methods into Web Services by simply clicking a form submit button. Some others of these methods are too generic to be made available as a Web Service without limiting the types of the inputs or outputs. For example, the method setPropertyValue takes a java.lang.Object as a method argument for the property value. Since Web Services dont allow java.lang.Object as an input (or output), this method cannot be used as a Web Service in this form. However, we can restrict the type of this argument using the code generator template functionality, so when the Web Service is generated, the outward-facing method will be strongly typed based on the property being set, and can simply call through to the more generic setPropertyValue method in the body of the Web Service. The RepositoryService class has the following properties:
Property Name transactionManager
Type
javax.transaction. TransactionManager
Description The service that manages any transactions that are used to execute repository methods on this instance. The component that manages mapping files based on repository and item descriptor name combinations. For any methods that return a RepositoryItem, this service will be consulted to retrieve mapping files to use when transforming these items into XML. See Mapping Files and XML Schemas in the Repository to XML Data Binding chapter for more information abut mapping files and the
ItemDescriptorMappingManager
mappingManager
atg.repository.xml. ItemDescriptorMappingManager
class. xmlGetService
atg.repository.xml. GetService atg.repository.xml. AddService
The service that knows how to turn RepositoryItems into XML. The service that knows how to add RepositoryItems in XML format to a repository.
xmlAddService
34
The service that knows how to take RepositoryItems in XML format and update them in their corresponding repositories.
xmlUpdateService
atg.repository.xml. UpdateService
For information about the XML service properties, see Repository Operations in the Repository to XML Data Binding chapter.
35
36
4 Repository to XML Data Binding
One of the key aspects of integrating the ATG platform with a remote system is sharing data between the two systems. Data sharing and synchronization are often complex, because the two systems may store their data in dissimilar formats. The ATG platform data is typically stored in a Dynamo repository, which handles the mapping of data in Java objects to the underlying data store (such as a SQL database). The ATG Integration Framework includes a data binding facility for reading and writing data between a repository and XML documents. Using this facility, you can write out repository data to XML documents that can then be read into a remote system, or read data into a repository from XML documents that store data from a remote system. A key aspect of this system is the use of mapping files to specify the data to include or exclude, and to map the names of repository properties to the names used by the remote system. The data binding facility also includes tools for generating XML Schemas that describe the structure of data in a repository, and to use these XML Schemas to validate the data written out from or read into the repository. 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 chapter discusses: Mapping Files and XML Schemas Repository Operations Note that the classes described in this chapter work only with repositories included in the initialRepositories property of the /atg/registry/ContentRepositories component.
Mapping Files and XML Schemas

In addition to the XML instance documents that store the actual data, data binding uses two other types of documents: Mapping files control which data is exchanged between system, and which data is omitted.
37
4 - Repository to XML Data Binding
XML Schemas describe the structure of the data, and can be used to validate XML instance documents.
Mapping Files
When you exchange data between the ATG platform and a remote system, you will typically want to exclude certain data. For example, an the ATG platform profile usually includes Dynamo-specific information about scenarios. When you create an XML instance document from data in a repository, Dynamo includes and excludes certain properties by default: If a property is readable and does not point to another item descriptor, it is included. If a property is readable, points to another item descriptor, and its cascade attribute is set to "delete", it is included. All other properties are excluded.
For more information about the default inclusion rules, see the isIncludeProperty() method of the
atg.repository.xml.RepositoryXMLTools class in the ATG API Reference. RepositoryXMLTools is a
utilities class with various methods for encoding and decoding item descriptors, property names, and mapping files to and from XML-compatible namespaces and identifiers. If you want more explicit control over the properties that are written out, you can use a mapping file. A mapping file specifies what properties to include or exclude when moving data between a repository and an XML instance document, and provides a way to map the names of Dynamo properties to their equivalents in a remote system. For example, a Dynamo profile might have an email property that stores the same information as the Email_Address attribute on another system. The following is the Document Type Definition (DTD) for mapping files:
<!-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
38
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>
Sample Mapping File

The following is a sample mapping file for the Dynamo profile repository:
<!DOCTYPE item-descriptor SYSTEM "http://www.atg.com/dtds/databinding/itemDescriptorMapping_1.0.dtd"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true"> <property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false">
39

</property> </item-descriptor>
</item-descriptor> <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"/>
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 itemdescriptor 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 scenariorelated properties are excluded:
<property name="slotInstances" include="false"/> <property name="scenarioInstances" include="false"/> <property name="mailings" include="false"/> <property name="scenarioValues" include="false"/>
If a property is an item descriptor, there must be an item-descriptor tag inside the property tag. For example, the homeAddress property points to a contactInfo item descriptor:
<property name="homeAddress" include="true"> <item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="contactInfo" default-include="false"> </item-descriptor> </property>
Note that the item-descriptor tag for contactInfo can have property tags within it. The nesting of property tags and item-descriptor tags must reflect the hierarchy of the item descriptors in the repository. If you do not include a property tag for a property that points to an item descriptor (such as the homeAddress property shown above), the ATG platform uses the default inclusion rules for determining which properties of that item descriptor to include. Finally, the property tag has an optional targetName attribute for mapping the property name to its corresponding name in the remote system:
<property name="firstName" targetName="first_name"/>
40
Managing Mapping Files for Repository Item Descriptors

The ATG platform includes two classes that help identify the appropriate mapping file for each item descriptor that you want to use with the repository2xml data binding facility. These classes are used by Web Service clients:
atg.repository.xml.ItemDescriptorMapping atg.repository.xml.ItemDescriptorMappingManager
ItemDescriptorMapping
An ItemDescriptorMapping is a simple bean that holds information about relationships between repository item descriptors and mapping files. The mapping files describe what properties are to be exposed when an item from that item descriptor is to be transformed into XML. Each ItemDescriptorMapping pertains to exactly one repository: for example, you would have a UserProfileItemDescriptorMapping, or a PromotionItemDescriptorMapping component, each of which would provide a list of item descriptor names from the corresponding repository and their corresponding mapping files. An ItemDescriptorMapping contains only three properties:
Property Name
repositoryPath
Type
java.lang.String
Description The path to the repository supported by this

ItemDescriptorMapping. This
is a read-only property
repository atg.repository.Repository
The path to the repository supported by this

ItemDescriptorMapping. Similar to repositoryPath but this property will resolve to an actual Repository instance, and is writeable.
itemDescriptorMapping
java.util.Map
A map where the keys are item descriptor names and the values are locations of mapping files, relative to the configuration path, which provide rules for how an item of the keyed item descriptor name appears in XML format
Here is an example properties file for an ItemDescriptorMapping that supports the profile repository:
41
$class=atg.repository.xml.ItemDescriptorMapping repository=/atg/userprofiling/ProfileAdapterRepository itemDescriptorMapping=\ user=/atg/userprofiling/userMapping.xml,\ contactInfo=/atg/userprofiling/contactInfoMapping.xml
Here we see the there are two entries in the itemDescriptorMapping property, one for the user item descriptor, and one for the contactInfo item descriptor. Whenever an entry is added to the itemDescriptorMapping property, whether through a properties file, or directly in code, the ItemDescriptorMapping checks to make sure that the key of the entry, the item descriptor name, resolves to an actual item descriptor of the repository this service is configured to support. If any item descriptor name does not resolve, a RepositoryException is thrown. By themselves, ItemDescriptorMappings dont do any work. They simply hold state. In order to put them to work, you must add them to the ItemDescriptorMappingManager, described below.
ItemDescriptorMappingManager
Class: atg.repository.xml.ItemDescriptorMappingManager Component: /atg/repository/xml/ItemDescriptorMappingManager Module: DAS The ItemDescriptorMappingManager serves as a registry of ItemDescriptorMappings. It is through this service that you obtain mapping files for all repository and item descriptor combinations. The mapping files are registered in the itemDescriptorMappings property of the ItemDescriptorMappingManager component:
Property Name
itemDescriptorMappings
Type
atg.repository.xml. ItemDescriptorMapping[]
Description An array of
ItemDescriptorMapping
components. When a user calls methods to retrieve mapping files, this component sifts through the itemDescriptorMappings to determine the correct mapping.
Here is an example properties file:
$class=atg.repository.xml.ItemDescriptorMappingManager itemDescriptorMappings=\ /atg/userprofiling/UserProfileItemMapping,\ /atg/userprofiling/ContactInfoItemMapping
42
The following ItemDescriptorMappingManager methods can be used to retrieve mapping files:

getMappingFileName(String pRepositoryPath, String pItemDescriptorName)
Using the given repository path and item descriptor name, returns the mapping file for that given path:name combination, or null if none exists.
getMappingFileName(Repository pRepository, String pItemDescriptorName)
Using the given repository and item descriptor name, returns the mapping file for that given repository:name combination, or null if none exists. When you use the atg.repository.xml.GetService to get repository items in XML form, you can pass along a mapping file name using these ItemDescriptorMappingManager methods. Using the ItemDescriptorMappingManager, you can centralize all mapping files in one component for all item descriptors, and just call that to determine which mapping file to use for a given item descriptor.
XML Schemas
The ATG 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.
Generating XML Schemas

The ATG platform provides a command-line tool that generates an XML Schema for a given item descriptor. The XML generated by the Get data binding service conforms to this Schema. Similarly, the XML Schema describes an instance document that is capable of being processed by the Add, Update, or Remove service. The command-line tool is named generateXMLSchema.sh (on Unix) or generateXMLSchema.bat (on Windows) and is found in the <ATG10dir>/home/bin directory. The following table lists the arguments that can be supplied to this command:
-repository
Nucleus path to the repository containing the item descriptor that the XML Schema is being generated for. Required. Name of the item-descriptor that the XML Schema is being generated for. Required. 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. If set to true, then the Schemas will be saved via the configured XMLSchemaManager. If omitted, defaults to true. Specifies the mapping file to use. Not required.
-itemDescriptor
-outputDirectory
-saveSchemas
-mappingFile
43

-schemaGenerator -m -help
Nucleus path to the Schema Generator component. If omitted, defaults to /atg/repository/xml/SchemaGenerator. Specifies the set of modules to use in the repository definition. Required. Prints out a usage message. Not required.
Example
The following command generates an XML Schema for the user item descriptor of the default Dynamo profile repository, using the properties defined in the repository definition file for the DSSJ2EEDemo application module (and the modules required by the DSSJ2EEDemo module):
generateXMLSchema -m DSSJ2EEDemo repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user
The generated XML Schema is saved by the Schema Manager specified by the schemaManager property of the Schema Generator component. The default Schema Generator is the /atg/repository/xml/SchemaGenerator component, and its schemaManager property points by default to the /atg/repository/xml/SchemaManager component. Note that if the user item descriptor contains other item descriptors as properties, the generated Schema will reflect these other item descriptors as well. To save the Schema to the current working directory in addition to the directory determined by the XMLSchemaFileDirectory property of the Schema Manager:
generateXMLSchema -m DSSJ2EEDemo repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -outputDirectory .
Managing Schemas and Mapping Files

As mentioned above, the default Schema Generator has a schemaManager property that points to the /atg/repository/xml/SchemaManager component. In addition, each of the data binding service components (described below) has an XMLSchemaManager property that points to this SchemaManager component. This component is of class atg.repository.xml.XMLSchemaManager. This class, which extends atg.repository.databinding.MappingManager, manages XML Schemas and mapping files. For example, this class has mappingFileDirectories and XMLSchemaFileDirectory properties that specify the directories where mapping files and Schemas are stored. Note that Schemas must have the extension .xsd and mapping files must have the extension .xml. For example, suppose you want to generate an XML Schema and specify a mapping file to use. The command would look something like this:
generateXMLSchema -m DSSJ2EEDemo repository /atg/userprofiling/ProfileAdapterRepository -itemDescriptor user -mappingFile profileMapping.xml
44
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:
<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
atg.repository.xml.GetService
Nucleus component
/atg/repository/xml/GetService
45
atg.repository.xml.AddService atg.repository.xml.UpdateService atg.repository.xml.RemoveService
/atg/repository/xml/AddService /atg/repository/xml/UpdateService /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 API Reference for more information.
Getting Repository Items

You use getItemAsXML() method of the atg.repository.xml.GetService class to create XML documents from repository items. This method takes a repository item as an input argument and returns a String containing an XML representation of this item. If you write out this String (e.g., to a file), be sure to use the same character encoding that the repository uses. Some versions of the getItemAsXML() method take additional inputs for specifying a String array of the names of the properties to write out or a String containing the name of the mapping file to use. If you supply only a repository item as input, the method uses the default inclusion rules (described in the Mapping Files section) to determine which properties to include. By default, GetService writes out an XML document as a single line, because it is intended to be machine-readable. If you want the generated XML to be human-readable, set the indentXMLOutput property of the GetService component to true. The resulting XML will have appropriate line breaks.
Example
Suppose you want to generate XML for a user profile, based on a mapping file named profileMapping.xml. The following code finds the user repository item whose ID is "user747" and generates an XML representation of it:
RepositoryItem userItem = getProfileRepository().getItem("user747", "user"); String userAsXML = GetService.getItemAsXML(userItem,"profileMapping.xml");
The following is sample output from this code. The data represents the profile of the user sandy in the Quincy Funds demo:
<user:user xmlns:user="http://www.atg.com/ns/profileMapping/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/profileMapping/UserProfiles/user profileMapping+UserProfiles+user.xsd " ID="user747"> <user:securityStatus>0</user:securityStatus> <user:actualGoals>long-term</user:actualGoals> <user:gender>female</user:gender> <user:fundShares> <user:integer>500</user:integer>
46
<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> <user:guests>false</user:guests> <user:brokers>false</user:brokers> <user:investors>true</user:investors> </user:user>
Namespaces
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 "
47
The xsi:schemaLocation attribute specifies the URL and name of the Schema file. The Schema filename (profileMapping+UserProfiles+user.xsd) is determined by the name of the mapping file (profileMapping.xml), the name of the repository (UserProfiles), and the item descriptor (user). If no mapping file is used to create the document, the Schema filename indicates the repository and item descriptor. If you want the Schema filename to include the entire pathname, set the appendRelativeSchemaLocation property of the GetService component to true. This is especially important if youre using an external Schema verification tool, which will generally need the complete pathname to find the Schema file. If you use a mapping file when you create an instance document, you should be sure to supply the name of this mapping file to the generateXMLSchema command (using the mappingFile argument) when you generate the Schema. Otherwise the actual Schema filename will not match the name in the xsi:schemaLocation tag, and the Schema may not accurately reflect the data in the instance document; as a result, you may not be able to validate the data when reading it into a remote system (or reading it back into Dynamo using AddService). Note also that if your call to getItemAsXML() includes an input argument that specifies the names of properties to write out, the Schema will not accurately reflect the data in the instance document, so validation will not be possible. To avoid any conflict between tag names, the XML tags in the generated instance document are named using the convention itemType:propertyName; for example the user:userType tag stores the value of the userType property of the user item type. If the addItemTypeToPropertyNames property of the RepositoryXMLTools component that GetService points to is set to true, the tags are named using the convention itemType:itemType.propertyName; in this case, the tag name would be user:user.userType. By default addItemTypeToPropertyNames is set to true, because the resulting XML is less likely to result in naming collisions.
Adding Repository Items

You use the addItem() method of the atg.repository.xml.AddService class to create new repository items from XML documents. This method takes an XML document as an input argument and returns a repository item. The XML document can be in the form of a String, a java.io.Reader, or a java.io.InputStream. The method examines the schemaLocation attribute in the XML document to determine if there is a mapping file associated with the document. Some versions of the method take additional arguments for specifying how to handle missing or empty tags, and whether the data should be validated against a Schema. For some examples of how a repository item might look in XML document form, see the <ATG10dir>/RL/Example/j2ee-apps/example/web-app/public directory. The Repository Loader (RL) module also includes a page you can use to generate XML documents from existing repository items. This page is located at <ATG10dir>/RL/Example/j2ee-apps/example/web-app/itemAsXml.jsp. Note that addItem() cannot create new read-only elements in a repository. By default, any data in the instance document that corresponds to a read-only element in the repository is silently ignored. If you want addItem() to log a warning each time it skips a read-only element, set the logWarningOnReadOnly property of the AddService component to true.
Validating the Data

The addItem() method can optionally validate the data in an XML instance document against the Schema specified in the instance document. Validation is enabled or disabled by the validate property
48
of the AddService component. By default, this property is set to false, because validation slows down processing of the document. To enable validation, set the validate property to true. The addItem() method can also take a Boolean argument to specify whether to validate the document. The value of this argument overrides the validate property. If you do not specify this argument, addItem() uses the validate property to determine whether to validate the document. If you are confident that your data is valid, you can disable validation, and the instance document will be processed more quickly. However, if the data turns out to be invalid, the invalid data may be written to the repository. If you enable validation and the data is invalid, addItem() does not write the contents of the instance document to the repository.
Updating Repository Items

You use the updateItem() method of the atg.repository.xml.UpdateService class to modify a repository item. For example, the following instance document updates a users email address:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress> </user:user>
The updateItem() method can optionally validate the instance document against the specified Schema. The logic for this is similar to the AddService.addItem() method: the UpdateService component has a validate property whose default value is false, and the updateItem() method can take a Boolean argument that overrides the value of the validate property.
Selecting the Item to Update

There are two ways to select the item to update: You can specify the item explicitly when you call updateItem(). You can specify a set of match properties, and updateItem() selects the item whose values match the corresponding values in the instance document.
For example, the login property is often used for matching, because it is unique to a specific user item and its value does not change. The following XML instance document could be used to select the item and then update its emailAddress property:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress> <user:user.login>sandy</user:user.login> </user:user>
49
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. For more information, see Namespaces in the Getting Repository Items section. The matchProperties array can contain any number of property names. If the value of each repository item property named in matchProperties matches its corresponding attribute in the XML instance document, the item is selected for update. All of the specified properties must match for the item to be selected; for example, if matchProperties lists login and lastName properties, the values of both properties must match. If multiple items are selected, an exception is thrown and no update occurs. Matching is limited to top-level properties of the repository item. Subproperties (such as properties of other repository items) cannot be matched. So, for example, if a user item has a lastName property that is a String, you can include lastName in matchProperties; but if a user item has a shippingAddress property that is another repository item, you cannot include, say, shippingAddress.city in matchProperties. If a property has been mapped to a different name in the instance document, the name to match on is the property name used in the repository, not the instance document. For example, suppose you use a mapping file to map a user items dateOfBirth property to the name birthday, like this:
<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="true"> <property name="dateOfBirth" targetName="birthday"/>
The corresponding instance document might look like this:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.birthday>02-06-1975</user:user.birthday> </user:user>
To specify this property in matchProperties, you use the name of the property as it is defined in the repository (dateOfBirth), not the target name (birthday). For example:
String[] matchProperties = {"dateOfBirth"};
You can configure the UpdateService to add a repository item if an attempt to update does not find a match. If you want the UpdateService to add items when no items are matched, set the addWhenNoMatchedItems property of the UpdateService to true.
50
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.
repositoryId
The repositoryId attribute of an item can be used as a special match property. If the repositoryId String is passed to UpdateService as a match property, the service will determine the value of this attribute from the top-level XML element in the instance document, and then find a repository item with a matching repository ID. The following XML example uses the repositoryId attribute as a match property:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747" repositoryId="user707"> <user:user.emailAddress>sandy@example.com</user:user.emailAddress> </user:user> String[] matchProperties = {"repositoryId"}; RepositoryItem updatedItem = UpdateService.updateItem(inputXML, matchProperties);
In this case, the UpdateService selects the user item whose repositoryId is "user707" from /atg/userprofiling/ProfileAdapterRepository. Note: Do not confuse with the repositoryId attribute, which identifies a repository item, with the ID attribute used in the XML schema to identify an XML element. The repositoryId attribute and not the ID attribute is used to identify which repository item to update.
Removing Repository Items

You use the removeItems() method of the atg.repository.xml.RemoveService class to delete repository items specified in XML documents. This method takes an XML document in the form of a String array, a java.io.Reader, or a java.io.inputStream. Some versions of removeItems() take a matchProperties String array. Property matching for RemoveService.removeItems() uses the same logic as UpdateService.updateItem(), except it is legal for multiple repository items to be marked for deletion. For example, an instance document to remove all users whose date of birth is 02-06-1975 would look like:
<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user UserProfiles+user.xsd " ID="user747"> <user:user.dateOfBirth>02-06-1975</user:user.dateOfBirth> </user:user>
51
The application then uses the following code to remove all the user repository items whose dateOfBirth value is 02-06-1975 (assuming the inputXML String contains the instance document shown above):
String[] matchProperties = {"dateOfBirth"}; String[] removedItemIds = RemoveService.removeItem(inputXML,matchProperties);
The maximum number of matching items is specified by the maxSelectedItems property of RemoveService. If the number of matching repository items exceeds this value, an exception is thrown. In the /atg/repository/xml/RemoveService component, maxSelectedItems is set to 5 by default.
52
5 Accessing ATG Web Services from Java Clients
The ATG platform permits external Java clients to access Nucleus methods by exposing them as ATG Web Services. Many such ATG Web Services are included with the ATG platform, as are tools for creating custom Web Services. For a list of ATG Web Services, see ATG Web Services. Java clients can execute those Web Services through calls that are translated into XML wrapped in SOAP, transmitted to the ATG platform, and routed to the Nucleus method itself. Other ATG resources, such as JMS messages and RepositoryItems, can also be exposed as ATG Web Services. The ATG implementation of Web Services follows the standard Web Service guidelines outlined by JAXRPC 1.0 and SOAP 1.1 specifications. ATG recommends that you use Apache Axis 1.4 to create your Web Service calls, and this chapter includes code examples that assume you are using Axis. This chapter aims to inform you how to call ATG Web Services from an Axis client. Rather than provide a broad discussion on how to use Axis, this chapter describes ATG-specific features and processes that you need to be familiar with. Please see the Axis documentation for comprehensive instructions. To access an ATG Web Service, you need to be familiar with the following topics: About ATG Web Services Before You Begin Using a Java Client Writing a CookieContainer Class Calling ATG Web Services From a Java Client Creating a Serializer and Deserializer
About ATG Web Services

For the most part, you call ATG Web Services in the same way you call Web Services elsewhere. While the general process may not differ, its important that you are aware of these platform-specific features.
Security
The content you see as a response to a Web Service call depends on your access privileges. When you login using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent Web Service calls in that session are associated with that identity and related role.
53
5 - Accessing ATG Web Services from Java Clients

Transactions
For more information on loginUser, see the ATG Personalization Programming Guide. You may also want to learn how other Web Services handle the security information provided by loginUser. Such information exists in the ATG Repository Guide and the ATG Commerce Programming Guide.
When a client calls a Web Service, the transactional behavior of the service is managed entirely on the server side. The method that is exposed as a Web Service can use standard transaction demarcation techniques, but the calling client has no control over this. There are some practical considerations you should be aware of. If a single Web Service call attempts to perform some operation, and the operation fails, the operation can be rolled back (provided that the Nucleus method is demarcated properly). However, a transaction cannot span multiple Web Service calls so if an operation is performed by a sequence of Web Service calls, and the final call fails, there is no way to roll back the steps performed by the previous calls.
Sharing Sessions
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. 2. 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. 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 chapter includes an example of a helper class that you can use to simplify cookie management. See Writing a CookieContainer Class.
RepositoryItems
If your Web Services access RepositoryItems, you need to provide a serializer and deserializer so the RepositoryItem content can be interpreted by non-ATG systems. The following Web Services transmit content thats natively stored as RepositoryItems:
getProfile getRepositoryItem performRQLQuery getOrderAsXML (Commerce users only) getOrdersAsXML (Commerce users only) getProductXMLById (Commerce users only) getProductXMLByDescription (Commerce users only) getProductXMLByRQL (Commerce users only)
54
getProductSkusXML (Commerce users only) getPromotionsAsXML (Commerce users only)
The ATG 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 for more information.
Before You Begin Using a Java Client

Before you can access a Web Service, you need to make sure the ATG platform is ready for your call and Axis 1.4 is configured: 1. 2. Confirm that the application that includes the Web Service is deployed on your application server and is running. For more information, see Deploying Web Services. Download Axis 1.4 from the Apache web site:
http://ws.apache.org/axis
3. 4.
Extract the contents of the Axis download file. Add the axis libraries to your CLASSPATH.
See the Apache site for more information about using Axis.
Writing a CookieContainer Class

The following example shows a sample CookieContainer class. You can use this as a model for your own class. Note that: This class relies on the Axis API. If you are using a different Java client, you will need to use the API for your client. This class works with both static and dynamic Web Service calls. (See Calling ATG Web Services from a Java Client.) If you always make only one of these call types, your own CookieContainer class does not need to handle both cases.
package com.example.webservice; import org.apache.axis.MessageContext; import org.apache.axis.client.Call; import org.apache.axis.client.Stub; import org.apache.axis.transport.http.HTTPConstants; /** * A class that can be passed between web service clients that keeps track of * the cookies received from the server. These cookies are then used by
55

**/ {
* subsequent web service client calls in order to ensure that session * state is maintained. public class CookieContainer //------------------------------------// Member variables //------------------------------------/** Array of cookies from the Set-Cookie HTTP header **/ private String[] mCookies = null; /** Array of cookies from the Set-Cookie2 HTTP header **/ private String[] mCookies2 = null; //------------------------------------// Methods //------------------------------------/** * Gets the cookies set by the Set-Cookie HTTP header * @return the cookies from the Set-Cookie HTTP header, which * may be null **/ public String[] getCookies() { return mCookies; } /** * Gets the cookies set by the Set-Cookie2 HTTP header * @return the cookies from the Set-Cookie2 HTTP header, which * may be null **/ public String[] getCookies2() { return mCookies2; } /** * Extracts the cookies from the given Axis MessageContext, and * sets the cookies and cookies2 properties from them. * @param pContext the Axis message context to examine. This * cannot be null **/ public void extractCookies(MessageContext pContext) { mCookies = (String[])pContext.getProperty (HTTPConstants.HEADER_COOKIE); mCookies2 = (String[])pContext.getProperty (HTTPConstants.HEADER_COOKIE2); }
56
/** * 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); } }
57
Calling ATG Web Services from a Java Client

When you call a Web Service, you create resources that describe the Web Service you want to call, its location, and initial inputs. Axis then takes those resources and produces from them a SOAP message that it then sends to the Web Service itself. There are two ways to create a Web Service call: Use a client stub to create a static Web Service call. Use the Dynamic Invocation Interface to create a dynamic Web Service call.
The main distinction between the two processes is the data types they can handle. Because using Web Services requires that data be converted into several formats from a native format into an XML representation of that format back into the native form it is important that you choose a process designed to work with the data types accessed by the Web Services you want to employ. The static process can handle any data type regardless of whether its primitive, complex, object, or nonstandard. Non-standard types may require some extra effort as is the case when accessing ATG RepositoryItems or JMS messages. The dynamic process, conversely, is limited to only working with object versions of these data types (as permitted by SOAP 1.1): Boolean Byte Double Float Int Long Short
Some complex types such as Array, List, Set, and Map may be supported using the dynamic process in a restricted way. See the JAX-RPC Specification for details on data type restrictions. The subsequent sections describe how you would make a call to the loginUser ATG Web Service following the static and dynamic processes.
Creating a Call Using a Client Stub (Static)

When you create a call following the static method, you represent the server-side Web Service architecture on the client by creating a client stub and a client: The client stub describes the associated Web Services resources as well as the remote procedure call that the Web Service executes. The client configures a particular Web Service instance by specifying initial values and methods on various Web Services resources.
The call is constructed by compiling information from the client stub, client, and various other supporting classes that hold static information.
58
For example, to create a static call to the loginUser Web Service: 1. 2. 3. 4. Create and compile the client stub, if one does not already exist for the Web Service. See Creating and Compiling a Client Stub below. Add the client stub to the CLASSPATH variable so the client stub is available to local Web Services resources. Create and compile the client. See Creating and Compiling a Client below. Use Axis to execute the Web Service call:
loginStub.createUser(pProfileAsXML)
The format of this call is clientStub.web_service(generated_web_Service_Call_instance) Axis creates the XML message, wraps it in SOAP, and sends it via HTTP to the Web Service location in the client stub.
Creating and Compiling a Client Stub

The client stub describes the Web Service method and supporting resources in a structure thats familiar to the client. Each Web Service requires a stub for each client that executes it. You can reuse a stub for subsequent calls so you only need to create it once. However, simultaneous calls to a Web Service made by different threads will require that a unique client stub instance exists for each thread. To create and compile a client stub for the loginUser Web Service: 1. Locate the active WSDL file via HTTP for the Web Service you want to call. The URL is provided in with the documentation that describes each Web Service: For Repository Web Services, see the ATG Repository Guide. For Personalization Web Services, see the ATG Personalization Programming Guide. For Commerce Web Services, see the ATG Commerce Programming Guide. Its important that you access the runtime and not the static version of the WSDL document. Assuming that you included the modules holding the Web Services you want to access when you assembled your application, you should be able to download the runtime version of the WSDL. 2. 3. Use the Axis WSDL-to-Java tool to generate the client stub based on the WSDL. Compile the client stub.
Creating and Compiling a Client

A Web Service client is a Java file that describes precisely what the Web Service should do. It provides the actions the Web Service should commit and initial values. If you want to enable Web Services to share sessions, your code needs to pass cookies between calls. The following example, which creates a static Web Service call to the loginUser Web Service, uses the CookieContainer class shown in Writing a CookieContainer Class:
59
LoginUserSEIService loginService = new LoginUserSEIServiceLocator(); LoginUserSEI loginStub = loginService.getLoginUserSEIPort(); org.apache.axis.client.Stub axisStub = (org.apache.axis.client.Stub) loginStub; CookieContainer cookieContainer = new CookieContainer(); axisStub.setMaintainSession(true); // Don't allow XML elements to reference other XML elements axisStub._setPropertyValue(AxisEngine.PROP_DOMULTIREFS, new Boolean(false)); // Push cookies onto the Stub cookieContainer.pushCookies(stub); String userId = loginStub.loginUser("bhavern", " xyo8bnif", false); // Get cookies out of the Stub, and pass them to subsequent calls as needed cookieContainer.extractCookies(stub); }
Creating a Call Using the Dynamic Invocation Interface (Dynamic)

A dynamic Web Service call holds all relevant information in one file, the client, which Axis converts directly into the SOAP message. Essentially, the client you create is a Java version of the call itself, excluding some relative values that are replaced with absolute ones at compile time. Keep in mind that if you want to access a Web Service that uses non-standard data types, you need to create your Web Service call following the static process. See Creating a Call Using a Client Stub (Static). If you want to enable Web Services to share sessions, your code needs to pass cookies between calls. The following example, which creates a dynamic Web Service call to the loginUser Web Service, uses the CookieContainer class shown in Writing a CookieContainer Class:
Service service = new Service(); Call call = (Call) service.createCall(); // Get a hold of a CookieContainer passed to this method/class CookieContainer cookieContainer = new CookieContainer(); // Push previous cookies (if any) to the new Call object cookieContainer.pushCookies(call); call.setMaintainSession(true); call.setTargetEndpointAddress(new java.net.URL("http://hostname:port/userprofiling/usersession/loginUser/ loginUser") ); // Don't allow XML elements to reference other XML elements call.setProperty(AxisEngine.PROP_DOMULTIREFS,Boolean.FALSE)
60
call.addParameter("Login", org.apache.axis.Constants.XSD_STRING, javax.xml.rpc.ParameterMode.IN); call.addParameter("Password", org.apache.axis.Constants.XSD_STRING, javax.xml.rpc.ParameterMode.IN); call.addParameter("IsPasswordEncrypted", org.apache.axis.Constants.XSD_BOOLEAN, javax.xml.rpc.ParameterMode.IN); call.setReturnType(org.apache.axis.Constants.XSD_STRING); call.setOperationName(new QName("http://www.atg.com/webservices", "loginUser")); String userId = (String) call.invoke( new Object[] { "bhavern", "xyo8bnif", Boolean.FALSE } ); // Extract new cookies from the Call into the CookieContainer object, // which can then be passed to subsequent calls cookieContainer.extractCookies(call); }
Creating a Serializer and Deserializer

When you want to use a Web Service that accesses RepositoryItems, you can create a mechanism for translating foreign content into different formats: A serializer will convert content from a native format into XML that will eventually undergo another conversion into a RepositoryItem. You need to create a serializer for set operations in which the client sends content to the Web Service in the context of the call. A deserializer constructs XML content that was originally formatted as RepositoryItems into a native content format. You need to create a deserializer for get operations in which a Web call returns content that represents a RepositoryItem.
Both a serializer and a deserializer will need to understand the RepositoryItem schema. When you create the XML schema and a mapping file, youll need some information about the Web Service itself. You can find that information in the sections that describe the Web Service: For getProfile, see the ATG Personalization Programming Guide. For getOrderAsXML, getOrdersAsXML, getProductXMLById, getProductXMLByDescription, getProductXMLByRQL, getProductSkusXML, getPromotionAsXML, see the ATG Commerce Programming Guide. For Repository Web Services , see the ATG Repository Guide.
61

1. 2. 3.
Two Repository Web Services, getRepositoryItem and performRQLQuery, require a serializer and deserializer, but they can apply to any RepositoryItems you choose, which is different from the other Web Services that are only available to specific RepositorityItems and item descriptors. The serializers and deserializers you create require a Repository schema, which you can create by following these steps: Create a Mapping file that determines which RepositoryItem properties will be captured by the Web Service and returned by the call. See Creating a Mapping File. Use the generateXMLSchema tool to convert the RepositoryItem class into a standard XML schema. See Generating an XML Schema. Insert a reference to the XML schema in your instance document, which is a document that represents an instance of the Web Service call. You complete this step when you configure the client stub; see Creating and Compiling a Client Stub for instructions.
Creating a Mapping File

If you were to create an XML schema that included all RepositoryItem properties, some content may not be understood by standard deserializers and some may not conform to the XML 1.0 specification. Instead, you create a mapping file that determines which properties, from the RepositoryItem's item descriptor, to include or exclude from your XML schema. For instructions on how to create a mapping file, see Mapping Files. 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 ATG platform Dynamo Administration UI: 1. 2. 3. In Dynamo Administration UI, click the Component Browser link. Navigate to the Repository component that correlates to your Web Service as indicated in the documentation for your ATG Web Service. Click the See Property Descriptions link beside the item descriptor name. For the item descriptor name, see the documentation for your ATG 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: 1. 2.
RepositoryItem properties that accept primitive data types and may be null. RepositoryItem properties that accept Maps, Lists, or Sets.
Generating an XML Schema

The generateXMLSchema is a script that takes a given Repository component and item descriptor as arguments and produces an XML schema. For instructions on using this tools, see XML Schemas. When you create an XML schema in support of a Web Service, make sure that the same modules in the ATG platform are running now as those that will be running when the client calls the Web Service.
62
For a list of Web Services, associated Repository components and items descriptors, see the documentation for your ATG Web Service. You may find these two optional arguments helpful:
outputDirectory copies the resultant XML schema to the directory of your
choosing.
mappingFile specifies a file that describes the RepositoryItem properties to include in the resultant XML schema.
Other Required Schemas

When a client deserializes a RepositoryItem, it uses the schema derived from the item descriptor to reconstruct each repository object and its properties in the appropriate data types. Depending on the makeup of the item descriptor, you may need to also generate a schema for related item descriptors. Consider the Profile repository that uses the user item descriptor. There are two item descriptors,
broker and investor, that are subtypes of user. If you were to use the updateProfile Web Service
call while the Relationship Management platform is running, user and all subtypes of it that are part of Relationship Management are accessible. When you call updateProfile, its unclear which version of user you want to call: user, investor or broker. In this case, you need to generate XML schemes for all three item descriptors. In short, you need to generate an XML schema for all item descriptors used by RepositoryItems that are accessed by a Web Service call and for any related (parent or child) item descriptors that are running when the call is made. It is difficult to supply a general list of all item descriptors for which this added step applies because the contents of that list depend on many factors. When deciding if you need to create supplemental XML schemas for an item descriptor, consider the following: The Web Service you are calling The modules running when you call that Web Service The contents of your ATG module stack The custom ATG components you have created that may extend existing components accessed by the Web Service
Note: The previous discussion addresses item descriptors and their subtypes, meaning item descriptors that inherit from the parent class. This relationship should not be confused with that which item descriptors share with extensions of themselves, which are added by other modules. For example, the order item descriptor has one set of properties provided by the Consumer Commerce module. A second order item descriptor is supplied by Business Commerce and, when both modules are running, the order item descriptors are concatenated so that Business Commerce properties take precedence. Because all versions of order for the running module are combined into one, you need only one XML schema for the order item descriptor. When you create that XML schema for order, remember to do so while the same modules are running as will run when your Web Service calls that item descriptor.
63
64
6 Accessing ATG Web Services from .NET Clients
The ATG platform permits .NET clients to access Nucleus methods by exposing them as ATG Web Services. Many such ATG Web Services are included with the ATG platform as are tools for creating custom Web Services. For a list of ATG Web Services, see ATG Web Services. .NET clients are able to contact those Web Services through a carefully constructed call thats built in .NET, translated into XML wrapped in SOAP, transmitted to the ATG platform, and routed to the Nucleus method itself. Other ATG resources, such as JMS messages and RepositoryItems can also be exposed as ATG Web Services. This chapter aims to inform you how to call ATG Web Services from a .NET client. Rather than provide a broad discussion on how to use .NET, this chapter describes ATG-specific features and processes that you need to be familiar with. Please see your .NET documentation for comprehensive instructions. To access an ATG Web Service, you need to be familiar with the following topics: About Web Services in the ATG Platform Before You Begin Using a .NET Client Calling ATG Web Services from a .NET Client Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems
About Web Services in the ATG Platform

For the most part, you call ATG Web Services in the same way you call Web Services elsewhere. While the general process may not differ, its important that you are aware of these platform-specific features.
Security
The content you see as a response to a Web Service call depends on your access privileges. When you login using the loginUser Web Service, you provide your user identity. If session sharing is enabled, all subsequent Web Service calls in that session are associated with that identity and related role. For more information on loginUser, see the ATG Personalization Programming Guide. You may also want to learn how other Web Services handle the security information provided by loginUser. Such information exists in the ATG Repository Guide and the ATG Commerce Programming Guide.
65
6 - Accessing ATG Web Services from .NET Clients

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 ATG Web Services from a .NET Client. 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.
2.
Client Stubs
The ATG platform provides preconfigured client stubs for all ATG Web Services in ATGWS.dll. To use these stubs you need to install ATGWS.dll. See Installing ATGWS.dll for instructions. The client stubs provided here should be sufficient for your ATG Web Services. Note that simultaneous calls to a Web Service made by different threads will require that a unique client stub instance exist for each thread.
Web Services that Access RepositoryItems

Standard serializers and deserializers can handle some complex types, such as JMS messages sent to the ContentViewed and ContentRecommended ATG Web Services. When Web Services interact with proprietary technologies, such as RepositoryItems, standard serializers and deserializers dont understand the source data type so they arent able to recreate it. A RepositoryItem is a specialized JavaBean called a Dynamic Bean that produces basic get and set methods for the fields you define for it. Many complex items are stored by the ATG platform as RepositoryItems. The following Web Services transmit content thats natively stored as RepositoryItems:
getProfile getRepositoryItem
66
performRQLQuery getOrderAsXML (Commerce users only) getOrdersAsXML (Commerce users only) getProductXMLById (Commerce users only) getProductXMLByDescription (Commerce users only) getProductXMLByRQL (Commerce users only) getProductSkusXML (Commerce users only) getPromotionsAsXML (Commerce users only)
For these Web Services, you can use the Atg.DotNet.WebService API to serialize and deserialize related content. Descriptions for API classes are in Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems. You can find this API in ATGWS.dll, which you need to install in order to access them. See Installing ATGWS.dll.
Before You Begin Using a .NET Client

Before you can access a Web Service, you need to make sure the ATG platform is ready for your call and .NET is configured: 1. 2. 3. Confirm that the application that includes the Web Service is deployed on your application server and is running. For more information, see Deploying Web Services. Install Internet Information Service (IIS) and then Active Server Page.Net (ASP.NET) and VisualStudio.NET (VS.NET). Install ATGWS.dll so you can access the stub and API classes it contains. See instructions below.
Installing ATGWS.dll
ATGWS.dll is a library that includes a stub class for each ATG Web Service. It also provides the Atg.DotNet.WebService API used for serializing and deserializing RepositoryItems. All users who
want to access ATG Web Services from a .NET client should install ATGWS.dll. You need two versions of ATGWS.dll on your system. One version lives in you Global Assembly Cache (GAC) so ASP.NET is able to access it when compiling the Web Service call. Another version should exist in a location that VS.NET recognizes. The instructions provided here direct you to use GACutil, a utility provided by .NET, although you can use any utility that can install ATGWS.dll to the Assembly folder in your windows directory. While the library does not need to live on the same machine as .NET, .NET needs to be able to access it. To install ATGWS.dll: 1. Copy <ATG10dir>/DAS/os_specific_files/i486-unknownwin32/ATGWS.dll to your Windows\Assembly folder.
67

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

<DotNetdir>:\ gacutil/i <ATG10dir>/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 <ATG10dir>/DAS/os_specific_files/i486-unknownwin32/ATGWS
Calling ATG Web Services from a .NET Client

This section describes the components you need in order to call an ATG Web Service. Because there are a few ways that you can generate a Web Service call on .NET, this section focuses only on the ATG resources you will use and assumes that you will refer to your .NET documentation for specific instructions. The following sections should provide guidance when creating a Web Service call: Accessing an ATG Web Service Accessing a Custom ATG Web Service Sample Web Service Calls
Accessing an ATG Web Service

The ATG platform provides client stubs for all ATG platform Web Services in ATGWS.dll. Once you have installed a version of ATGWS.dll to your GAC and Assembly folders (see Installing ATGWS.dll for instructions), you need to do two things: 1. 2. In your Visual Studio .NET project, make a reference to ATGWS.dll. Create instances of the client stubs and use them in your Web Service call.
Accessing a Custom ATG Web Service

To access a Web Service that you created in the ATG platform, you create client stub and a reference to it in your Visual Studio.NET project: 1. 2. Assemble your application. Make sure you include the modules that contain the Web Services you want to access. Deploy the application on your application server and start it up.
68
3. 4.
In your Visual Studio .NET project, add the Web Services as Web References. When prompted for an Address, provide the WSDL URI, such as:
http://hostname:port/repository/generic/getItem?WSDL
You can find the URI for ATG Web Services in the documentation for the specific Web Service: For Repository Web Services, see the ATG Repository Guide. For Personalization Web Services, see the ATG Personalization Programming Guide. For Commerce Web Services, see the ATG Commerce Programming Guide.
Sample Web Service Calls

The Web Service call is a document that incorporates calls to any number of ATG Web Services that may exist in the same session. For each Web Service, you create an instance of the client stub, call methods on the Web Service, and call the Web Service itself. These Web Service calls are written in C#.
A Simple Call
This Web Service call obtains a RepositoryItem by accessing the getRepositoryItem ATG Web Service.
using Atg.DotNet.WebService.Repository.GetRepositoryItem; // ... // create stub instance GetRepositoryItemSEIService getItemClientStub = new GetRepositoryItemSEIService(); // assign URL of web service getRepositoryItemClientStub.Url = "http://example.com/repository/generic/getItem/getRepositoryItem"; // call web service string itemXml = getRepositoryItemClientStub.getRepositoryItem("/nucleus/path/to/repository", "itemDescriptorName", "repositoryId");
A Complex Call
The following code demonstrates how you would construct a call that uses security controls to restrict the information users can access. Notice that the loginUser Web Service establishes the user identity role, which other Web Services refer to. Because an instance of a CookieContainer is created in this code and assigned to each Web Service stub, all Web Services called here exist in the same session. For brevity these examples omit some details such as a exception handling for the SoapException as well as class syntax.
69
using System.Net; // for CookieContainer using Atg.DotNet.WebService.Repository.GetItem; using Atg.DotNet.WebService.Repository.PerformRQLQuery; using Atg.DotNet.WebService.UserSession.LoginUser; using Atg.DotNet.WebService.UserSession.LogoutUser; // create stub instances GetItemSEIService getItemClientStub = new GetItemSEIService(); PerformRQLQuerySEIService performRQLQueryClientStub = new PerformRQLQuerySEIService(); LoginUserSEIService loginUserClientStub = new LoginUserSEIService(); LogoutUserSEIService logoutUserClientStub = new LogoutUserSEIService(); // create a new cookie container for our session and share it between // the various stub instances CookieContainer cookieContainer = new CookieContainer(); getItemClientStub.CookieContainer = cookieContainer; performRQLQueryClientStub.CookieContainer = cookieContainer; loginUserClientStub.CookieContainer = cookieContainer; logoutUserClientStub.CookieContainer = cookieContainer; // authenticate the user for the session loginUserClientStub.loginUser("user", "password", false); // call services string itemXml = getItemClientStub.getItem("/nucleus/path/to/repository", "itemDescriptorName", "repositoryId"); string[] itemsXml = performRQLQueryClientStub.performRQLQuery("/nucleus/path/to/repository", "itemDescriptorName", "property = 'value'"); // log out the user logoutUserClientStub.logoutUser();
Using the Atg.DotNet.WebService API to Serialize and Deserialize RepositoryItems

The Atg.DotNet.WebService API is a mechanism that you can use to serialize and deserialize RepositoryItem content. The primary role of this API is to: Converts a RepositoryItem into an XML document (serialization). Formats an XML document into a RespositoryItem (deserialization).
70
By understanding the ATG RepositoryItem API, Atg.DotNetWebService.RepositoryItem is able to convert into objects any content that uses the RepositoryItem API for its underlying data type. You can use this API for ATG and custom Web Services that access RepositoryItems. The Atg.DotNet.WebService is made up of the following classes: RepositoryItem Class Property Class RepositoryItemRef Class ComplexType Class NoSuchPropertyException Class RepositoryItemSerializer Class RepositoryItemSerializationException Class
Note: Rather than use this API, you could generate an XML schema representation of the RepositoryItem and use that serialize/deserialize content. The advantage of using an XML schema is that you can control the properties you use, meaning you can easily exclude certain properties from your schema. You may find the disadvantages, namely the limitations in property types and values that this method supports, reason to use the provided API instead. For instructions on how to use an XML schema for serialization/deserialization, see the Creating a Serializer and Deserializer in the Java client chapter.
About the Atg.DotNet.WebService API

Collectively, these classes provide you with the ability to serialize and deserialize RepositoryItems and to configure both processes. Although this discussion specifically describes the serialization process, the same principles apply to both processes. When you want to deserialize content from a Web Service, for example, you use the response sent by ATG Web Service resulting from your initial Web Service call. The response, formatted in XML, holds a string object that represents ATG RepositoryItems. Once you make the call to the API to deserialize the string, the deserializer parses the string into a RepositoryItem object. Not all content in the string is emitted by the serializer. By default, only content specified as dirty, meaning a different value for it exists in the ATG platform and the external system .NET communicates with, is serialized. Once an item has been serialized, theres parity across systems so all properties on that item are marked as clean. You can alter the default dirty/clean designation in the following ways: Use the RepositoryItem.Dirty property to toggle an objects clean/dirty status. Use the RepositoryItem.setPropertyDirty() methods to toggle a propertys clean/dirty status.
During deserialization, content that represents RepositoryItem properties is parsed based on a few rules. All properties are converted back to the native data type, assuming that data type is available in .NET. The following data types dont exist in .NET and so values for these types are converted as follows: ATG Map properties use Hashtable data type in .NET. ATG Date or Timestamp properties are stored as .NET DateTime data type.
71
ATG Set properties are formatted as .NET Array data type. ATG properties that refer to other ATG RepositoryItems behave as .NET Hashtables.
For the most part, Atg.DotNet.WebService determines format output type by relying on prior processing. For example, if it had deserialized a particular RepositoryItem, such a Growth fund, then assuming no new properties are added, when the Growth fund is serialized, Atg.DotNet.WebService.RepositoryItem is aware of each propertys destination data type. However, in all other circumstances, you should explicitly include the XML data type for the property. In short, under these circumstances include data types: The first time a RepositoryItem is serialized when it hasnt been previously deserialized, such as in the case of adding a new item to the ATG platform. A new property value is assigned to an empty RepositoryItem.
Note: In order to use the classes in this interface, make sure that the ATG platform atg/repository/xml/RepositoryXMLTools component has the encodeRepositoryIdAsAttr property set to true. This is the default setting.
RepositoryItem Class
The Atg.DotNet.WebService.RepositoryItem class is designed to manage XML serialization and deserialization for easy interoperability with the .NET Web Services framework. To serialize or deserialize a RepositoryItem, you need only to pass in the RepositoryName and
RepositoryId. When you are working with content for the first time, you also need to call setPropertyType to instruct the deserializer/serializer to use a specific output data type.
Properties
Dirty Determines the overall dirtiness of an object by specifying whether all properties are clean (false) or one of more properties are dirty (true). ItemDescriptorName Name of the item descriptor associated with the objects RepositoryItem. Properties List of properties for this RepositoryItem. RepositoryId ID provided to the objects RepositoryItem representation. RepositoryName Name of the repository that the RepositoryItem is part of.
Constructors
RepositoryItem() Constructs a new, empty RepositoryItem object. When you serialize or deserialize a property with a
72
value that is a pointer to a RepositoryItem, be sure to supply it a RepositoryName, RepositoryId, and ItemDescriptorName when you invoke the setRepositoryItem method. RepositoryItem(string) Constructs a new RepositoryItem in the ATG platform, populating it with values parsed from the XML instance of the Web Service call. The XML instance is a by-product from the Web Service call generation.
Methods
clearPropertyValues Clears all property values for a given RepositoryItem. Before using RepositoryItemSerializer.deserialize, its a good idea to use this method to clear all previous values. isPropertyDirty Determines whether a given property value is dirty (true) or clean (false). setPropertyDirty Designates a given property as dirty. getPropertyValue Returns the value provided for a property in the ATG platform. If the property does not exist in the ATG platform, an error of type ATGWS.NoSuchPropertyException is thrown. setPropertyValue Sets a value for a property in the ATG platform. getPropertyType Returns the propertys XML data type. setPropertyType Specifies the XML data type for the property value. serialize Creates a string representation of an XML document for the RepositoryItem.
Property Class
This class represents a given propertys name and value.
Properties
Dirty Determines whether a given property is dirty (true) or clean (false). If you indicate that a property value should change by invoking the RepsoitoryItem setPropertyValue call, this property is set to true. Once a response is returned from the setPropertyValue call, this property is set to false. XmlType XML data type that will be used to represent the propertys value.
73

Constructor Methods
Property() Constructs an empty object representing a property.
getName Returns the name of the property. getValue Returns the value of the property. setValue Sets a new value to the property.
RepositoryItemRef Class
This class represents a reference to another RepositoryItem.
Properties
RepositoryName Name of the repository of which the referenced RepositoryItem is a part. ItemDescriptorName Name of the item descriptor used by the referenced RepositoryItem . RepositoryId ID for the referenced RepositoryItem .
Method
setRepositoryItem Initializes the ItemRef to refer to the provided RepositoryItem.
Complex Type Class

This class permits you to serialize/deserialize properties that use complex types by specifying an output data type explicitly.
Properties
TypeName Data type for the RepositoryItem property. Properties Name of any properties that are either deserialized from or serialized into the complex type.
74
Constructor
ComplexType() Constructs an empty object to represent all properties of a complex data type.
Methods
getPropertyValue Retrieves values from the ATG platform for the specified properties. If the property does not exist in the ATG platform, an error of type ATGWS.NoSuchPropertyException is thrown. setPropertyValue Sets a property to a value supplied as an input. getPropertyType Returns the XML data type for the property value. setPropertyType Specifies the XML data type for the property value.
NoSuchPropertyException Class
This class generates an exception each time a getProperty or getPropertyValue method tries to interact with a property that has not been specified for the designated RepositoryItem.
Properties
PropertyName Name of the property that you are trying to work with.
Constructor
NoSuchPropertyException Constructs the exception.
RepositoryItemSerializer Class
This class conducts serialization/deserialization and permits you to decide if you want all or only dirty properties to be updated. Constructors RepositoryItemSerializer() Constructs a serializer instance. RepositoryItemSerializer(RepositoryItem) Constructs an object holding serialized content.
75

Methods
deserialize (string) Deserializes an XML-formatted string into a new RepositoryItem. deserialize (string, boolean) Deserializes an XML document string into a RepositoryItem. Additional arguments true or false indicate whether values for only dirty properties (true) or all properties (false) should be deserialized. serialize (string) Serializes a RepositoryItem into an XML-formatted string document. serialize (boolean) Serializes a RepositoryIteminto an XML document. Additional arguments true and false indicate whether values for only dirty properties (true) or all properties (false) should be deserialized.
RepositoryItemSerializationException Class
This class creates an exception object when errors occur during serialization or deserialization. Constructor RepositoryItemSerializationException() Constructs an empty exception object.
76
In addition to the ATG Web Services functionality discussed in the preceding chapters, the ATG platform includes a more generalized framework that enables you to integrate your applications with remote software systems for cases where using Web Services might not be appropriate. For example, you could use the integration framework to integrate an ATG Commerce application with an order-processing system. When a customer places an order through ATG Commerce, the order data can be transferred to the order-processing system, and the ATG platform can trigger events that invoke the processing facilities in the remote system. The integration framework involves several key facilities that you can use to integrate ATG applications with remote systems: JMS messaging, configured through Patch Bay, to enable the ATG platform to trigger events in the remote system, or the remote system to trigger events in the ATG platform. See the Dynamo Message System chapter of the ATG Programming Guide. Remote Procedure Calls (RPC), for inter-application command execution. For example, the ATG platform can use RPC to query an inventory management system. Data integration, using the repository to XML data binding facility (described in Part I of this guide) and the Integration Repository.
You can use these facilities individually, but a typical integration will use all of these facilities together. For example, the Integration Repository typically uses RPC to execute the commands used to move data between the ATG platform and the remote system.
Integrators and Adapters

Integrating the ATG platform with a remote system generally involves additional software to handle the communication between the two systems: A middleware transport layer, such as Tibco or MQ Adapters that enable the ATG platform and the remote system to communicate through the middleware transport layer An integrator that implements the Integration Frameworks queries and commands in a form understood by the remote system, enabling the two systems to interoperate and share data
The following figure illustrates the ATG integration architecture:
77
You can write adapters and integrators by implementing the various APIs described in this manual. Note that ATG adapters handle only the communication between the ATG platform and the middleware transport. Adapters for communication between a remote system and a middleware transport are typically available from the company that develops the remote system or the middleware.
78
7 Using the Integration Repository
The ATG Integration Framework includes the Integration Repository, which adds to the ATG Repository feature the ability to represent data on external systems as ATG repository items. The Integration Repository provides several key features for integrating ATG with external systems: You can execute queries from ATG against remote systems. The Integration Repository represents the results of the queries as repository items. You can create queries using RQL or other ATG query building techniques, and the Integration Repository translates the queries into the format required by the remote system. When data from the remote system is represented as repository items, the Integration Repository can automatically submit changes to these items to the remote system without requiring special update calls to a remote system.
Architecture
The Integration Repository is a wrapper around an ATG SQL repository, which is referred to as the local repository. In a system architecture that uses an Integration Repository, the integrated data resides in the remote system, rather than just in a local database, and queries are made using the RPC command structure described in the Remote Procedure Calls chapter. Just like other repositories, an Integration Repository defines one or more item descriptors. Each item descriptor defines one or more commands to be used for the operations that need to interact with the remote system:
executeQuery getItem createItem updateItem removeItem
These operations are described in more detail in the Command Operations section of this chapter. Each command involves an RPC call that may access the remote system, as described in the Remote Procedure Calls chapter. The Integration Repository enables you to use the ATG Repository Query Language (RQL) and all the RQL droplets to access data that is stored on remote systems. The translation between RQL and the query
79
7 - Using the Integration Repository
format required by the remote system is handled by an implementation of the IntegrationRepositoryView class. An implementation of IntegrationRepositoryView typically needs to be written for each remote system you want to integrate with ATG. Wrapping the SQL repository provides the Integration Repository with superior performance and robustness by leveraging the SQL repositorys sophisticated item caching features. You can persist data from the remote system locally in a SQL repository. By maintaining locally-cached copies of the remote data, the Integration Repository can make the data available more quickly than if you needed to access the remote system every time you needed to access the data. In addition, the local SQL repository offers a degree of protection against the remote system being temporarily unavailable. More details of the Integration Repository architecture are described in the Integration Repository APIs section of this chapter.
Integration Approaches
The Integration Repository is designed to help integrate ATG applications with remote systems. It assumes that your business maintains data on a remote system and you want to expose and possibly modify this data within your ATG application in the form of ATG repository items. There are several ways you can set up such an integration, depending on the demands of your ATG application and the characteristics of the remote system and the data maintained there. Here are four possible approaches for getting remote data. Which approach to choose depends on balancing your need for consistent data and best performance.
Remote Only
In this case, the data is maintained only on the remote system. Each time that the ATG application needs to access the data, a command is issued to the remote system. The local repository is configured to use transient repository items. Advantages: You are always sure that the data returned to ATG is up to date.
Disadvantages: If the remote system is unavailable, then no form of the data is available to the ATG application. Frequent queries to the remote system can affect the performance of the remote system, which may also be serving functions other than the ATG application. The need to query the remote system will tend to slow the performance of the ATG application.
See Configuring the Remote-Only Model for more details about how this approach could be configured.
80
Remote then Local

In this case, the primary source for the data is the remote system. Each time that the ATG application needs to access the data, a command is issued to the remote system. If the command fails to return, then the command is issued to the local repository. Advantages: You are sure that the data returned to ATG is up to date, except in cases where the remote system is unavailable. In addition, the existence of the local repository can provide a backup form of the data, in case the remote system is inaccessible.
Disadvantages: Frequent queries to the remote system can affect the performance of the remote system, which may also be serving functions other than the ATG application. The need to query the remote system will tend to slow the performance of the ATG application.
See Configuring the Remote-then-Local Model for more details about how this approach could be configured.
Local then Remote

In this case, a version of the data is maintained in a local repository. Only if the data is not available locally, or if the local copy has been marked invalid or has expired, does the Integration Repository query the remote system for the data. You might use this integration model if you need to make sure the system is as fast as possible, and you dont have to worry so much about data consistency because the data does not change that often. When the remote system is down, you can block changes to the data (updates, creating and removing items), but you make the data available from the local system, so that your users can continue to work. Advantages: ATGs performance is as fast as possible. There are fewer queries to the remote system, so less burden is placed on the remote system. You can configure the lifetime of items in the local repository, so you can be assured that the data is not out of date by more than a specified amount of time.
Disadvantages: You have less assurance that the data returned from the local repository is consistent with the data in the remote system.
See Configuring the Local-then-Remote Model for more details about how this approach could be configured.
81

Local Only
Advantages:
This approach doesnt need to use the ATG Integration Framework. In this case, we periodically dump data from the remote system into the relational database used by the ATG application. The data is accessed by the SQL repository. Since this approach doesnt need to issue commands against the remote system in real time, there doesnt need to be an Integration Repository.
ATGs performance is as fast as possible. The only interaction with the remote system is a periodic batch data transfer, which probably can be scheduled to place a minimal burden on the remote system.
Disadvantages: The local repository is not updated in real time, so any changes in the remote system are reflected in the local repository and therefore in your Web application only after the scheduled data transfer.
Setting Up an Integration Repository

Here is a brief overview of the steps involved in setting up an Integration Repository: 1. Create and configure an Integration Repository. This is a component of class atg.adapter.integrations.IntegrationRepository. Configure the properties described in the IntegrationRepository section. Create the Integration Repositorys definition file, as described in the Defining an Integration Repository section. Create and configure your local repository. The local repository is a normal SQL repository. See SQL Repository Overview in the ATG Repository Guide for more information. Create the database schema for your local repository. Create any mapping files you desire for each item descriptor in the Integration Repository. See Mapping for more information. Create a subclass of IntegrationRepositoryView for each remote system you need to query. Create Commands that correspond to each of the command operations you want to define for your Integration Repository. See the Remote Procedure Calls chapter.
2. 3.
4. 5. 6. 7.
To set up a complete integration with a remote system, you will also need to perform many tasks that are outside the scope of this chapter. You will need to configure the transport layer that connects ATG to the remote system. You will also typically want to create a portlet (ATG Portal gear) or set of form pages to display and modify data from the remote system.
82
Defining an Integration Repository

The Integration Repository is defined by an XML template file. This file is specified by the definitionFile property of the IntegrationRepository component. The Integration Repository definition file defines the integration behavior, including the commands used for the executeQuery, getItem, createItem, updateItem, and removeItem integration operations. The elements of the Integration Repository definition file are described in the Integration Repository Definition File section. The commands are described in the Command Operations section. Since the Integration Repository wraps another repository, the underlying SQL repository also requires a definition file to define the repository item properties. You may also want to create mapping files to handle the relation of your repository item properties to the data maintained on the remote system. See the Repository to XML Data Binding chapter for more information. This is an example of what the Integration Repository definition file would look like. It defines a single item descriptor, named account, and specifies the Commands used to query, get, add, update, and remove account items:
<integration-repository-template> <header> <name>RemoteX Repository</name> </header> <item-descriptor name="account"> <query command="/atg/integrations/remotex/queries/AccountQuery" view="atg.integrations.remotex.RemoteXView"> </query> <get-item command="/atg/integrations/remotex/queries/AccountQuery"> </get-item> <add-item command="/atg/integrations/remotex/queries/AccountUpdateRPC"> </add-item> <update-item command="/atg/integrations/remotex/queries/AccountUpdateRPC"> </update-item> <remove-item command="/atg/integrations/remotex/queries/AccountDeleteRPC"> </remove-item> </item-descriptor> </integration-repository-template>
The Integration Repository definition file conforms to a DTD file at this URL:
http://www.atg.com/dtds/integrations/integration-repository_1.0.dtd
The Integration Repository is also configured using normal JavaBean properties. An IntegrationRepository component might be configured in a properties file like this:
83
$class=atg.adapter.integrations.IntegrationRepository repositoryName=MyStuff localRepository=/mystuff/MyLocalRepository definitionFile=/mystuff/irConfig.xml transactionManager=/atg/dynamo/transaction/TransactionManager integrationRepositoryTools=/atg/integrations/repository/IntegrationRepositoryTools persistentCacheManager=/atg/integrations/repository/PersistentCacheManager mappingManager=/atg/repository/xml/SchemaManager mappingTools=/atg/integrations/repository/MappingTools lockManager=/atg/dynamo/service/ClientLockManager
The IntegrationRepository section describes these properties.
Integration Repository APIs

The Integration Repository consists of a set of item descriptors. Each item is queryable through a RepositoryView using a QueryBuilder. Each item descriptor is associated with a particular Command or set of Commands. One of these Commands returns results that are converted to repository items of the given item descriptor. Other Commands are used for updating or deleting values in the remote system. The Integration Repository includes extensions to, or implementations of, the following repository classes. Each of these classes is in the atg.adapter.integrations package.
IntegrationRepository extends atg.repository.RepositoryImpl IntegrationRepositoryItemDescriptor extends atg.repository.ItemDescriptorImpl IntegrationRepositoryItem implements atg.repository.RepositoryItem, atg.repository.MutableRepositoryItem ChangedPropertyBean implements atg.repository.RepositoryItem, atg.repository.MutableRepositoryItem atg.repository.databinding.MappingRepositoryItem implements atg.repository.RepositoryItem, atg.repository.MutableRepositoryItem IntegrationRepositoryView extends atg.repository.RepositoryViewImpl
In addition, each IntegrationRepositoryItemDescriptor refers to one or more commands, which implement the atg.integrations.Command interface. The RPC call in a Command returns an object of the atg.integrations.CommandResult class. Command and CommandResult are discussed in the Remote Procedure Calls chapter.
84
IntegrationRepository
extends RepositoryImpl The IntegrationRepository references another repository, which is referred to as the local repository and which is a SQL repository. The IntegrationRepository is defined by a Nucleus properties file and an XML definition file. Each method call functions as described in the Methods section, forwarding the request either to the local repository or to the IntegrationRepositoryItemDescriptor, which then executes a Command against the remote system.
Properties
localRepository The SQL repository that acts as a local repository. The local repository is a normal SQL repository. It might be configured in a properties file like this:
//mystuff/MyLocalRepository.properties $class=atg.adapter.gsa.GSARepository definitionFiles=/mystuff/localConfig.xml repositoryName=MyLocalStuff groupContainerPath=/atg/registry/RepositoryGroups XMLToolsFactory=/atg/dynamo/service/xml/XMLToolsFactory transactionManager=/atg/dynamo/transaction/TransactionManager dataSource=/atg/dynamo/service/jdbc/JTDataSource idGenerator=/atg/dynamo/service/IdGenerator
definitionFile The Integration Repository definition file. This is an XML file that uses the Integration Repository DTD, http://www.atg.com/dtds/integrations/integration-repository_1.0.dtd . See Integration Repository Definition File for information about creating an Integration Repository definition file integrationRepositoryTools This is a property of type atg.adapter.integrations.IntegrationRepositoryTools. This class provides a set of helper methods that are used to convert between the local repository items and the remote systems data format. An instance of this class exists at /atg/integrations/repository/IntegrationRepositoryTools. persistentCacheManager This is a property of type atg.adapter.integrations.PersistentCacheManager. This class provides management of persistent caching. An instance of this class exists at /atg/integrations/repository/PersistentCacheManager. See the Persistent Caching section. mappingManager This is a property of type atg.repository.databinding.MappingManager. You can optionally define a mapping of the local repository item to the data on the remote system. This class manages that mapping. See Mapping in this chapter and see also the Repository to XML Data Binding chapter.
85
mappingTools This is a property of type atg.repository.databinding.MappingTools, which is a helper class to manage the mappings. An instance of this class exists at /atg/integrations/repository/MappingTools. defaultTimeoutResponse The Integration Repository needs to deal with the case of a Command timing out before a result is returned from the remote system. If the Command times out, this property defines what the default behavior should be. There are four choices:
ROLLBACK INVALID
Rollback the current transaction. Mark the items state as invalid. See Persistent Caching. Mark the items state as unknown. See Persistent Caching. Do nothing.
UNKNOWN
IGNORE
sendScenarioEvents A boolean property that controls whether the repository sends scenario events. The Integration Framework includes one scenario event by default, atg.adapter.integrations.IntegrationExternalIdChange, which is sent when the externalId of an item is set. To trigger this event, use the IntegrationRepositoryTools.externalIDWasUpdated method.
Methods
Most methods in the IntegrationRepository class are pass-throughs to the local repository. The following methods provide special behavior: getItem Depending on how you have configured the Integration Repository, this method either: calls localRepository.getItem and, if the result is null, then calls IntegrationRepositoryItemDescriptor.getRemoteItem, or calls IntegrationRepositoryItemDescriptor.getRemoteItem and, if the result is null, then calls localRepository.getItem, or calls IntegrationRepositoryItemDescriptor.getRemoteItem only.
Both the local repositorys query cache and the IntegrationRepositorys query cache will be used depending on the item descriptor. If the IntegrationRepository definition file includes a query Command, then the IntegrationRepository executes the query (and uses its query cache). If there is no query Command, then the query is forwarded to the local repository. For a more detailed description, see getItem in the Command Operations section.
86
getView This method can operate in two ways. If querying is implemented in the local repository (no query command) then this returns a LocalRepositoryViewWrapper. If a Command is used for querying then this returns the configured RepositoryView class. getItemDescriptor Return an IntegrationRepositoryItemDescriptor that wraps an item descriptor from the local repository. The local repositorys item cache will be used. getItemForUpdate getItemsForUpdate Return one (or more) IntegrationRepositoryItem, using similar behavior to the getItem method above. createItem Call localRepository.createItem. This method is just a pass through. See addItem. addItem Call localRepository.addItem. Also call
IntegrationRepositoryItemDescriptor.addRemoteItem. For a more detailed description, see
addItem in the Command Operations section. updateItem Call localRepository.updateItem. Also call
IntegrationRepositoryItemDescriptor.updateRemoteItem. For a more detailed description, see
updateItem in the Command Operations section. removeItem Call localRepository.removeItem. Also call
IntegrationRepositoryItemDescriptor.removeRemoteItem. For a more detailed description, see
removeItem in the Command Operations section. Each of the Command executions is relevant only if the given command is defined for the item descriptor.
IntegrationRepositoryItemDescriptor
extends ItemDescriptorImpl This class references an item descriptor from the local repository. Most operations will be pass-throughs to the local repository item descriptor. The following operations (described in the Command Operations section) execute a Command if one is defined for the item descriptor; otherwise they do nothing.
executeQuery getItem updateItem addItem removeItem
In addition, this class is responsible for converting the results of queries obtained from the remote system into repository items.
87
IntegrationRepositoryItem
implements RepositoryItem, MutableRepositoryItem This class references a repository item in the local repository. Most operations will be pass-throughs to it.
ChangedPropertyBean
implements RepositoryItem, MutableRepositoryItem This class includes only the external ID property plus the list of properties in a RepositoryItem that have been changed. When, for example, updateItem is invoked on an IntegrationRepositoryItem, this wrapper can be passed to the update Command instead of the RepositoryItem. This allows us to send only the changed properties to be saved to the remote system, instead of trying to update all the properties of a repository item. For example, if you change the middleName property of the user profile, and the user profile is configured with an external id property called remoteId, the ChangedPropertyBean will only expose two properties: middleName and remoteId. If you call ChangedPropertyBean.getPropertyDescriptors, the result will only contain these two properties. A ChangedPropertyBean is read-only.
atg.repository.databinding.MappingRepositoryItem
implements RepositoryItem, MutableRepositoryItem A MappingRepositoryItem wraps a repository item and exposes properties as they are configured in a mapping file. The Integration Repository creates MappingRepositoryItems automatically if it is configured with a mapping file. The property names that are exposed are the target names as defined in the mapping file. If a propertys include attribute is false in the mapping file, then that property is not a legal property of the MappingRepositoryItem. For example, if the following mapping exists:
<item-descriptor repository-path="/atg/userprofiling/ProfileAdapterRepository" name="user" default-include="false"> <property name="firstName" include="true"/> <property name="lastName" include="true"/> <property name="id" target-name="dynamoId" include="true"/> </item-descriptor>
then the corresponding MappingRepositoryItem would contain three properties: firstName, lastName, and dynamoId. See the Repository to XML Data Binding chapter.
IntegrationRepositoryView
extends RepositoryViewImpl
88
IntegrationRepositoryView is an abstract class that provides some standard operations like applyOptions and getRange. For each type of remote system that you want to integrate with, you need
to create an implementation of IntegrationRepositoryView specific for your remote system in order to provide the translation between the ATG Query format, and the format expected by the remote system. When a query is executed, the executeUncachedQuery method is called. That method looks like this:
public RepositoryItem[] executeUncachedQuery(Query pQuery, QueryOptions pOptions) { // Step 1 Object input = createQueryCommandInput(pQuery, pOptions); // Step 2 RepositoryItem[] items = executeQueryCommand(input); // Step 3 return applyOptions(items, pOptions); }
The inputs to this method are a standard Query object and a standard QueryOptions object. The executeUncachedQuery method goes through the following steps: Step 1 The first thing the view needs to do is translate the Query object into an object that is understandable by the remote system. This is the responsibility of your subclass of IntegrationRepositoryView and the only method that you must implement. Step 2 This step is a call to the method defined in IntegrationRepositoryView that gets the correct Command according to your configuration and calls Command.execute with the provided query input. Step 3 This step may not be necessary. If your remote system supports sorting and ranging (returning a subset of the items) then it will be more efficient for that information to be included in the command input. In that case this step can be skipped in the executeUncachedQuery and you should override the applyOptions method to do nothing. The only thing required for querying to work is to subclass IntegrationRepositoryView and implement createQueryCommandInput. The implementation of this method will introspect the Query class and create an input object. The type and contents of the input object depend on the requirements of your application and the remote system you are querying. You then need to create a Command that knows what to do with this input. In addition, you will typically need to implement a processResults method in your IntegrationRepositoryView subclass. This method is responsible for translating between the remote data format and the repository items in the local repository. The default implementation of IntegrationRepositoryView.processResults calls
IntegrationRepositoryTools.createRepositoryItems. It passes in the results from
89
pCommandResult.getResults() as the first argument. The createRepositoryItems method uses DynamicBeans to look at the given command results. For each object in the result it uses the IntegrationRepositoryItemDescriptor to find the external ID. It uses this external ID to look for an existing item in the local repository with the same external ID. If one is found, this method iterates across the properties in the result object (using DynamicBeans) and updates the properties. If one is not found, a new item is first created, then the properties are updated.
Command Operations
The Integration Repository can define five types of operations that allow ATG repository items to access data in remote systems: executeQuery getItem addItem updateItem removeItem
executeQuery
There are four possibilities here: Always query against the local repository. For example, you may decide that updates to profiles need to be sent to a remote system, but queries of that data will always be done locally. Always query against the remote system. For example, you may want the data to remain in the remote system with no persistent storage in Dynamo. Check the local repository first, then check the remote system. Check the remote system first, then Dynamo.
If there is a Command associated with the query operation then the remote system is queried. If no Command is configured, then the local repository is queried. When you want to execute a query against the Integration Repository, your code will look something like this:
Repository rep = getRepository(getMyRepository()); RepositoryView view = rep.getView(getMyView()); QueryBuilder builder = view.getQueryBuilder(); Query query = builder.createSomeQuery(MyQueryExpression); RepositoryItem[] results = view.executeQuery(query);
90
There is no Integration Repository specific code in any of this. This is because you build queries with the Integration Repository in exactly the same way that you would build queries with the SQL repository. This also means that you can use RQL. You can use standard query builder calls, so the Query object that gets generated is a standard Query object from the atg.repository.query package. This real difference is in the RepositoryView. The Integration Framework uses a subclass named
IntegrationRepositoryView. This class provides an implementation of executeUncachedQuery that
is expected to call the query Command. There needs to be a subclass of IntegrationRepositoryView for each remote system you want to query. This subclass is responsible for translating between the ATG Query and the query format expected by the remote system. A query Command will receive whatever input is created by the createQueryCommandInput method of your IntegrationRepositoryView. The IntegrationRepositoryView.processResults method is responsible for translating between the remote data format and our repository items.
getItem
The getItem operation returns the value from the local repository. If there is no result, or if the entry in the local repository is invalid, the getItem operation updates the local repository with the results returned by the execution on the remote system of the Command associated with the getItem operation. This operation uses the IntegrationRepositoryItemDescriptor.getRemoteItem() method. Commands executed for get-item will receive whatever input is created by IntegrationRepositoryTools.createGetCommandInput(). By default this is a map of the external ID property name to the value of the external ID. If you require a more complex command input, extend IntegrationRepositoryTools and override the createGetCommandInput() method. If the item descriptors use-external-id attribute is true, then the given local repository item ID is identical to the remote ID. If this attribute is false, then the remote ID must be retrieved from the local item (using the item descriptors external-id-property). If getRemoteItem throws an exception, then if the item descriptors use-local-on-failure attribute is true, the operation returns the value from the local repository. Otherwise, the exception is passed on.
updateItem
The updateItem operation updates the values of the repository items properties both in the local repository and the remote system. The update is handled transactionally, so that if the update of the remote system fails, the change to the local value will not occur. This operation uses the IntegrationRepositoryItemDescriptor.updateRemoteItem() method. If the Integration Repository item descriptor defines a mapping file for the updateItem operation, then the updateItem operation creates a MappingRepositoryItem. If the changed-properties-only attribute is true, then the updateItem operation creates a ChangedPropertyBean. Otherwise, the IntegrationRepositoryItem is used.
91
The input for the updateItem Command is either the IntegrationRepositoryItem, the MappingRepositoryItem, or the ChangedPropertyBean as appropriate. It returns a CommandResult. The updateItem operation checks if there is an external ID in the CommandResult returned by the updateItem Command. If there is, the updateItem operation updates the external ID property of the local repository item with the value. If update-local-with-result is set to true, then the Integration Repository looks in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item. If the updateRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the updateItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
updateItem and Derived Properties

If your underlying local repository uses the derived properties feature of the SQL repository and you are using the changed-properties-only attribute set to true, then you should define a derivedproperties element to specify how the derived properties are handled. The derived-properties element is a container for a list of derived properties mapped to some property that is used in the derivation. It ensures that if the value of a property that is one of the derivation expressions of a derived property is changed, the Integration Repository treats the derived property itself as changed as well. The derived-properties element can optionally be used as a child element of an update-item tag. It is a container for one or more property elements, each of which has a name attribute and a referencedproperty attribute. The name attribute is the name of a property that can be derived from the referenced-property. The name attribute and referenced-property attribute must both be valid property names defined within the given item descriptor. If changed-properties-only="true" in the update-item element, then whenever the referencedproperty is sent in the update command, the name property will be as well. For example, suppose you have a property named remoteAddress that can be derived from a property named businessAddress. By including this derived-properties element in the update-item element, then whenever the businessAddress property is included as a changed property, the remoteAddress property will also be included as a changed property:
<derived-properties> <property name="remoteAddress" referenced-property="businessAddress"/> </derived-properties>
If you do not configure the derived-properties element for any derived properties in your item, then a change to a derived propertys expression will not cause the derived property itself to appear as a changed property. See SQL Repository Data Models: Derived Properties in the ATG Repository Guide for more information about derived properties.
addItem
The addItem operation adds the item to the local repository and to the remote system. If the addItem operation fails on the remote system, then the item will not be added to the local system. Since the item is
92
being newly added to the remote system, it is impossible to know in advance what value of the external ID is. The addItem operation attempts to set the external ID property with the result of the addItem Command. If the use-external-id attribute is true, then a change to the ID results in a clone of the item passed into this operation. This operation uses the IntegrationRepositoryItemDescriptor.addRemoteItem() method. The input for add-item Commands is the RepositoryItem being added. If the Integration Repository item descriptor defines a mapping file, then the addItem operation creates a MappingRepositoryItem. Otherwise, the IntegrationRepositoryItem is used. When the addItem Command returns successfully from the remote system, the addItem operation checks if there is an external ID in the CommandResult. If there is, the addItem operation updates the external ID property in the local repository with the ID value. If update-local-with-result is set to true, then the Integration Repository looks in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item. If the item was cloned, the original item is removed and the new item is returned. If the addRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the addItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
removeItem
The removeItem operation removes the item from the local repository and from the remote system. This operation uses the IntegrationRepositoryItemDescriptor.removeRemoteItem() method. If there is a mapping file defined in the item descriptor, the target name of the external ID property is used. If the useExternalId is false, then the given ID is the local repository item ID. The input for commands executed for remove-item is whatever input is created by IntegrationRepositoryTools.createRemoveCommandInput(). By default this is a map of the external ID property name to the value of the external ID. If you require a more complex command input, extend IntegrationRepositoryTools and override the createRemoveCommandInput() method. If the remove operation in the remote system fails, the local item will not be removed. If the removeRemoteItem call times out, the response depends on the setting of the timeout-response attribute for the removeItem operation. The possible settings are ROLLBACK, INVALID, UNKNOWN, IGNORE.
Mapping
The ATG Integration Framework provides tools to help you map ATG repository items to data objects on the remote system. Rather than export all the properties of a repository item in an integration command, you can define a map of repository item properties to attributes of the remote systems data objects. The mapping file controls which properties are sent as input in a Command, and what the external names of those properties are. For details about repository item mapping, see the Repository to XML Data Binding chapter.
93

Persistent Caching
The Integration Framework uses a separate SQL repository to track integration information. This SQL repository is referred to as the persistent cache or the Integration Data repository. This repository exists to track when particular repository item properties have been fetched from the remote system. This lets the Integration Framework limit the frequency with which it needs to access the remote system. The Integration Data repository has a Nucleus address of
/atg/integrations/repository/IntegrationData. You should not need to do anything to
configure or use the Integration Data repository. The repository uses a database table named if_integ_data that is created when you install ATG. The Integration Data repository defines a single item descriptor, named integration-data. For each repository item in the local repository, there is a corresponding repository item in the Integration Data repository. The integration-data item descriptor defines five properties:
Property
itemID
Description The repository ID of the repository item in the local repository that this information applies to. The name of the item descriptor in the local repository that this information applies to. The name of the local repository. This property tracks whether the item in the local repository is up to date with the data in the remote system. The state can be one of OK, INVALID, or UNKNOWN. Unless the state is OK, then the Integration Repository tries to get the data from the remote system, rather than relying on the local repository. This property tracks the last time a getItem operation retrieved the items data from the remote system. If the current time minus the lastRun time exceeds the local-value-timeout value set in the Integration Repository, then this item is marked INVALID and the Integration Repository retrieves the items data from the remote system with a getItem operation.
itemDescriptor
repositoryName state
lastRun
The item descriptor definition in the Integration Repository definition file specifies a local-valuetimeout attribute:
<item-descriptor name="my-item" local-value-timeout="1000"/>
The state of a repository item can be set to one of OK, INVALID, or UNKNOWN. The state can be changed if an Integration Repository command returns an error or times out. The Integration Repository checks the state and lastRun values on a get-item operation. If the state is INVALID, or the lastRun time for the given command is more than local-value-timeout milliseconds from the current time, then the item is reloaded from the remote system (using the get-item Command). If an item is transient, then a transient instance of the Integration Data repository item would be created.
94
An item descriptor in the Integration Repository can also define one or more read-only states. If the state of an item in the Integration Data repository is in a read-only state, then the values in the local repository can be used for read-only operations (query, get) but not for write operations (update, add, remove).
Cleaning up the Persistent Cache

The Integration Framework includes a scheduled service named CleanIntegrationData (class atg.adapter.integrations.CleanIntegrationData extends atg.service.scheduler.SingletonSchedulableService). This service is a Nucleus component with the address /atg/integrations/repository/CleanIntegrationData. It is responsible for cleaning up the persistent cache. The CleanIntegrationData service deletes from the Integration Data repository any records that have not been updated since the time specified by its expireTimePeriod property. If its deleteInvalidStateItems property is set to true, then records that are not in the state IntegrationRepository.OK will also be deleted. Note that the corresponding repository items are not deleted from the local repository. The CleanIntegrationData component has the following configurable properties:
Property Name
expireTimePeriod
Description Time in seconds that items remain in the persistent cache after they are last updated. Items are deleted if their state is not OK. See Scheduler Services in the Core Dynamo Services chapter of the ATG Programming Guide for information about how to set schedules in schedulable services.
Default Value 864000 (10 days)
deleteInvalidStateItems schedule
true
Configuration Examples
The following examples show some ways to configure three of the alternatives described in the Integration Approaches section: Configuring the Remote-Only Model Configuring the Remote-then-Local Model Configuring the Local-then-Remote Model
Configuring the Remote-Only Model

The Remote Only model is sketched in the Integration Approaches section. In this use case model, the data is maintained only on the remote system. Each time that the ATG application needs to access the data, a command is issued to the remote system.
95
To configure this integration model, configure your Integration Repository with transient properties. None of the repository item properties will be stored in the local repository database, so there are no table tags defined in the local repository definition file. In addition, the local-value-timeout attribute in the item descriptors of the Integration Repository is set to a small value. For example, the local repository definition might look like this: localRepositoryDefinition.xml
<gsa-template> <item-descriptor name="contact" display-property="lastName"> <property name="id" data-type="string"/> <property name="firstName" data-type="string" display-name="First Name"/> <property name="lastName" data-type="string" display-name="Last Name"/> <property name="email" data-type="string" display-name="Email Address"/> </item-descriptor> </gsa-template>
You can define a mapping file that specifies the names of these properties on the remote system: mapping.xml
<item-descriptor repository-path="/atg/integrations/remotex/RemoteXIntegrationRepository" name="contact"> <property name="id" targetName="Id" include="true"/> <property name="firstName" targetName="First Name" include="true"/> <property name="lastName" targetName="Last Name" include="true"/> <property name="email" targetName="Email Address" include="true"/> </item-descriptor>
The Integration Repository definition file would then look like this: integrationRepository.xml
<integration-repository-template> <item-descriptor name="contact" external-id-property="id" use-external-id="true" mapping-file="/atg/integrations/remotex/mapping.xml" local-value-timeout="1000"> <query command="/atg/integrations/remotex/GetContacts" view-class="atg.integrations.remotex.RemoteXQueryView"/> <get-item command="/atg/integrations/remotex/GetContacts" use-local-on-failure="false"/> <update-item command="/atg/integrations/remotex/UpdateContacts"/> </item-descriptor> </integration-repository-template>
96
This configuration means that queries and getItem operations use the GetContacts command. Users cannot remove or create contacts in the remote system, since no Command has been defined for these operations, but can update existing ones. If the remote system is unavailable in a getItem operation, then no data is available, since the use-local-on-failure attribute is set to false. Note that you could change this to provide ATG with read-only access to the remote system by omitting the updateItem Command, leaving only the GetContacts Command to query and get items.
Configuring the Remote-then-Local Model

The Remote then Local model is sketched in the Integration Approaches section. In this case, the primary source for the data is the remote system. A local copy of the data is maintained in the local repository. Each time that the ATG application needs to access the data, a command is issued to the remote system. If the command fails to return, then the command is issued to the local repository. To configure this integration model, use persistent properties that are stored through the local repository in a database on the local system. These persistent properties are defined within table tags in the local repository item descriptors. For example: localRepositoryDefinition.xml
<gsa-template> <item-descriptor name="contact" display-property="lastName"> <table name="contact" ... > <property name="id" data-type="string"/> <property name="firstName" data-type="string" display-name="First Name"/> <property name="lastName" data-type="string" display-name="Last Name"/> <property name="email" data-type="string" display-name="Email Address"/> </table> </item-descriptor> </gsa-template>
integrationRepository.xml The Integration Repository definition file uses the local-value-timeout attribute with a small value, so that subsequent attempts to access an item will continue to try the remote system before resorting to the local repository. In addition, the use-local-on-failure attribute for the getItem command is set to true.
<integration-repository-template> <item-descriptor name="contact" external-id-property="id" use-external-id="true" local-value-timeout="1000"> <query command="/atg/integrations/remotex/GetContacts" view-class="atg.integrations.remotex.RemoteXQueryView"/> <get-item command="/atg/integrations/remotex/GetContacts" use-local-on-failure="true"/>
97
<update-item command="/atg/integrations/remotex/UpdateContacts"/> </item-descriptor> </integration-repository-template>
Configuring the Local-then-Remote Model

The Local then Remote model is sketched in the Integration Approaches section. In this case, a version of the data is maintained in a local repository. Only if the data is not available locally, or if the local copy has expired or otherwise been marked invalid, do we query the remote system for the data. To configure this integration model, use persistent properties that are stored through the local repository in a database on the local system. The local repository is defined pretty much the same way as in the Configuring the Remote-then-Local Model. The Integration Repository definition is a bit different. It uses the local-value-timeout attribute with a large value, so that items will remain valid in the local repository for a reasonable length of time. integrationRepository.xml
<integration-repository-template> <item-descriptor name="contact" external-id-property="id" use-external-id="true" local-value-timeout="3600000"> <query command="/atg/integrations/remotex/GetContacts" view-class="atg.integrations.remotex.RemoteXQueryView"/> <get-item command="/atg/integrations/remotex/GetContacts" use-local-on-failure="true"/> <update-item command="/atg/integrations/remotex/UpdateContacts" timeout-response="UNKNOWN"/> <add-item command="/atg/integrations/remotex/AddContacts" timeout-response="INVALID"/> <remove-item command="/atg/integrations/remotex/RemoveContacts"/> </item-descriptor> </integration-repository-template>
Integration Repository Definition File

The XML definition file for Integration Repositories conforms to the integration-repository Document Type Definition with the URL:
http://www.atg.com/dtds/integrations/integration-repository_1.0.dtd
The definition file includes the following elements: integration-repository-template tag
98
header tag item-descriptor tag item-descriptor Child Tags
integration-repository-template tag
The integration-repository-template tag acts as a container for the Integration Repository definition file. It contains a single header tag and one or more item-descriptor tags.
header tag
The header tag contains information about the Integration Repository definition file. It can contain the following child elements:
name author version description
item-descriptor tag
Each item descriptor in the local repository that is integrated must be defined in the Integration Repository definition file and configured in the item-descriptor tag. This tag has the following attributes:
Attribute
name
Description The name of the item descriptor being configured. This must match the name of the item descriptor in the local repository. This is the default mapping file that is used when sending a repository item to any of the configured commands. The mapping file controls which properties are sent as input, and what the external names of those properties are. See Mapping. Just as there is a local ID (repositoryId) for each item in the local repository, there must also be an ID for each corresponding item in the remote system. This attribute identifies which repository item property in the local repository will be used to store the external ID. The external ID property does not have to be the same property as the repository ID in the local repository. If it is not, set use-external-id to false. If the local repository ID should match the external ID, then this property should be set to true. If the external ID is just stored as a non-ID property on the local item, then set this property to false.
mapping-file
external-idproperty
use-external-id
99

local-valuetimeout read-only-states
This property configures the number of milliseconds that a local item is valid before it should be retrieved from the external system. For example, if this is set to 600000, and you call getItem, then each subsequent call to getItem for the next 10 minutes will return that same item with no updates. After 10 minutes, a call to getItem will once again execute the getItem command. Each item retrieved from the remote system has a state associated with it in the persistent cache. The state can be one of OK, INVALID, or UNKNOWN. The default value is UNKNOWN. This property identifies which of those states will render the item read-only. This is useful if you timed out on a recent call to getItem and you still want people to be able to view the item but do not want to run the risk of them changing it. See Persistent Caching. This attribute controls the behavior if there is no configured command for a particular operation. If this attribute is true, then the local repository can act on the local repository item without reference to the remote system. For example, if there is no update-item command configured, and someone calls updateItem, is this an error? Should the update just go to the local repository with no Command execution?
allow-localoperation
item-descriptor Child Tags

The item-descriptor tag has five possible child tags: query tag get-item tag add-item tag update-item tag remove-item tag
The operations defined by these tags are also described in the Command Operations section.
query Tag
This configures the behavior of the Integration Repository when the executeQuery method is called on the RepositoryView for items of this type.
query Tag Attributes

command This is the Nucleus path to the Command implementation that will perform the query of the remote system. view-class If the default view class is not sufficient for querying items of this type, this subclass of atg.adapter.integrations.IntegrationRepositoryView will be used for queries instead.
100
query-cache-size This is the same as the SQL repository attribute of the same name. How many queries will be cached at a time? query-expire-timeout The time in milliseconds that each query cache entry remains valid.
get-item Tag
This configures the behavior of the Integration Repository when getItem is called for repository items of this type.
get-item Tag Attributes

command This is the Nucleus path to the Command implementation that will get the item from the remote system. Usually, the Command for getting is the same as the Command for querying. use-local-on-failure If this attribute is set to true then a locally cached value will be used in cases that the Command fails. For example, if the remote system is unavailable, the locally cached item will be returned to the user. If the remote item has never been retrieved before, this attribute has no effect.
update-item Tag
This configures the behavior of the Integration Repository when updateItem is called for repository items of this type. It can optionally contain a derived-properties tag as a child element. See updateItem and Derived Properties in the Command Operations section.
update-item Tag Attributes

command This is the Nucleus path to the Command implementation that will update the item in the remote system. mapping-file If the mapping file that is defined on the item descriptor is insufficient for creating input to the update Command, a different mapping file can be configured here. One common use for this is to exclude readonly properties from the input. timeout-response This defines the behavior in response to a CommandTimeoutException thrown by the update item Command. If this is not set, then the repositorys defaultTimeoutResponse property will be used instead. The possible settings for this attribute are: ROLLBACK, INVALID, UNKNOWN, IGNORE. The default is ROLLBACK. changed-properties-only If this is set to true, then only properties that have changed will be passed to the update item Command. The external-id-property is always included.
101
update-local-with-result If this is set to true, then the Integration Repository will look in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item. ignore-external-id-change If this is set to true, then if the only changed property on the item is the external ID property, no call to the update item Command will be made.
add-item Tag
This configures the behavior of the Integration Repository when addItem is called for repository items of this type.
add-item Tag Attributes

command This is the Nucleus path to the Command implementation that will add the item to the remote system. mapping-file If the mapping file that is defined on the item descriptor is insufficient for creating input to the add Command, a different mapping file can be configured here. One common use for this is to exclude readonly properties from the input. timeout-response This defines the behavior in response to a CommandTimeoutException thrown by the add item Command. If this is not set, then the repositorys defaultTimeoutResponse property will be used instead. The possible settings for this attribute are: ROLLBACK, INVALID, UNKNOWN, IGNORE. The default is ROLLBACK. update-local-with-result If this is set to true, then the Integration Repository will look in the CommandResult for new property values. Any values that appear in the result will be set on the local value of the item.
remove-item Tag
This configures the behavior of the Integration Repository when removeItem is called for repository items of this type.
remove-item Tag Attributes

command This is the Nucleus path to the Command implementation that will remove the item from the remote system. timeout-response This defines the behavior in response to a CommandTimeoutException thrown by the remove item Command. If this is not set, then the repositorys defaultTimeoutResponse property will be used instead. The possible settings for this attribute are: ROLLBACK, INVALID, UNKNOWN, IGNORE. The default is ROLLBACK.
102
derived-properties Tag
If your underlying local repository uses the derived properties feature of the SQL repository and you have set changed-properties-only="true" in the update-item element, then you should define a derived-properties element to specify how the derived properties are handled. The derivedproperties element is a container for a list of derived properties mapped to some property that is used in the derivation. The derived-properties element can optionally be used as a child element of an update-item tag. See updateItem and Derived Properties in the Command Operations section. See also SQL Repository Data Models: Derived Properties in the ATG Repository Guide for more information about derived properties. The derived-properties element contains one or more property tags.
property Tag
The property tag in the Integration Repository definition file is a child element of a derivedproperties element.
property Tag Attributes

A property tag in a derived-properties element uses the following attributes:
name
The name of a property that can be derived from the referencedproperty.
referenced-property
The name of a derivation expression of a derived property specified by the name attribute.
If changed-properties-only="true" in the update-item element, then whenever the referencedproperty is sent in the update command, the property specified by the name attribute will be as well. See updateItem and Derived Properties in the Command Operations section.
integration-repository Document Type Definition

<?xml encoding="UTF-8"?>         <!ENTITY % timeoutresponses "(ROLLBACK|UNKNOWN|INVALID|IGNORE)"> <!ELEMENT integration-repository-template (header?, item-descriptor*)>  <!ELEMENT header (name?, author*, version?, description?)>  <!ELEMENT name (#PCDATA)>  <!ELEMENT author (#PCDATA)>  <!ELEMENT version (#PCDATA)>  <!ELEMENT description (#PCDATA)>
     <!ELEMENT item-descriptor (query?, get-item?, update-item?, add-item?, remove-item?)>
<!ATTLIST item-descriptor name CDATA #REQUIRED mapping-file CDATA #IMPLIED external-id-property CDATA #IMPLIED use-external-id CDATA #IMPLIED local-value-timeout CDATA #IMPLIED read-only-states CDATA #IMPLIED allow-local-operation CDATA #IMPLIED > <!ELEMENT query EMPTY>
104
<!ATTLIST query command CDATA #IMPLIED view-class CDATA #IMPLIED query-cache-size CDATA #IMPLIED query-expire-timeout CDATA #IMPLIED > <!ELEMENT get-item EMPTY> <!ATTLIST get-item command CDATA #IMPLIED use-local-on-failure CDATA #IMPLIED > <!ELEMENT update-item (derived-properties?)> <!ATTLIST update-item command CDATA #IMPLIED mapping-file CDATA #IMPLIED timeout-response %timeoutresponses; "ROLLBACK" changed-properties-only CDATA #IMPLIED update-local-with-result CDATA #IMPLIED ignore-external-id-change CDATA #IMPLIED > <!ELEMENT derived-properties (property+)> <!ELEMENT property EMPTY> <!ATTLIST property name CDATA #REQUIRED referenced-property CDATA #REQUIRED > <!ELEMENT add-item EMPTY> <!ATTLIST add-item command CDATA #IMPLIED mapping-file CDATA #IMPLIED timeout-response %timeoutresponses; "ROLLBACK" update-local-with-result CDATA #IMPLIED > <!ELEMENT remove-item EMPTY> <!ATTLIST remove-item command CDATA #IMPLIED timeout-response %timeoutresponses; "ROLLBACK" >
105
106
8 Remote Procedure Calls
The integration framework includes a facility for making remote procedure calls (RPC). The Integration Repository makes extensive use of RPC to make calls to the remote system for querying and data synchronization. The RPC facility is designed to be as generic as possible in order to support a variety of remote systems and middleware transports. The classes and interfaces in the atg.integrations package provide an API that can be implemented in various ways to work with Web Services, the Java Connector Architecture (JCA), or different middleware transports. For example, the ATG Tibco Adapter includes an implementation of the RPC API that enables the ATG platform to execute Tibco commands. This chapter discusses the following topics: RPC API Architecture Implementing the RPC API Executing Commands in Pages
RPC API Architecture

The core pieces of the ATG RPC API architecture are:
atg.integrations.Command interface generic representation of a command atg.integrations.CommandHandler interface executes a command, and
performs pre- or postprocessing

atg.integrations.CommandResult class encapsulates the results of a command
To implement the RPC API, you create classes that implement the Command or CommandHandler interface, and return CommandResult objects. This section discusses the expected behavior of these classes. Note that some of this behavior is not enforced by the interfaces, but is nonetheless required by the API. For additional information about Command, CommandHandler, and CommandResult, see the ATG API Reference.
Command Interface
The atg.integrations.Command interface is a generic representation of a command. You create specific commands by implementing this interface.
107
8 - Remote Procedure Calls
The Command interface has two methods for executing commands, execute() and invokeRPC(). Both of these methods take a java.lang.Object as input (to be as generic as possible), and return a CommandResult. The execute() method is the one actually called by an application. Invoking this method sets off a chain of actions that ultimately results in the invokeRPC() method being executed. The invokeRPC() method does the actual work of making a call to the remote system. Note, however, that applications should not call this method directly, as the processing of commands is based on the assumption that execute() is called first. The Command.execute() method must implement the following logic: If the Command points to a CommandHandler (that is, if the Command.commandHandler property is not null), pass the Command and its input to that CommandHandler by calling the CommandHandler.executeCommand() method. If the Command does not point to a CommandHandler, call the Command.invokeRPC() method.
CommandHandler Interface
The atg.integrations.CommandHandler interface is a generic representation of a handler class for preprocessing and postprocessing commands. Command handlers are not a required part of the RPC API, since a Command.execute() method can call the corresponding Command.invokeRPC() method directly. However, command handlers add a great deal of power and flexibility to the RPC system. To pass a Command and its input to a CommandHandler, the Command.execute() method calls the
CommandHandler.executeCommand() method. The CommandHandler.executeCommand() method
must implement the following logic: If the CommandHandler points to another CommandHandler (that is, if the
CommandHandler.nextCommandHandler property is not null):
Perform any preprocessing. Pass along the Command and its input to the next CommandHandler by calling CommandHandler.getNextCommandHandler().executeCommand(). Perform any postprocessing. If the CommandHandler does not point to another CommandHandler: Perform any preprocessing. Execute the Command.invokeRPC() method. Perform any postprocessing. This logic allows command handlers (and the services they implement) to be chained together. The final CommandHandler in the chain must be able to call the Command.invokeRPC() method, to ensure that the command can be executed. However, it is not required that the command is always executed. For example, one typical use for a command handler is caching of commands and their results. Such a command handler might work like this: Examine the command to determine if it is in the cache. If the command is in the cache, return the cached result.
108
If the command is not in the cache, execute the command, return the result, and cache the command and result.
CommandResult Class
When a Command or CommandHandler object executes a Command, it must return a CommandResult. A CommandResult is just a container that has two other objects as properties: The result property is a java.lang.Object that is the actual object returned by the remote call. The context property is a java.util.Map that can be used to store additional parameters and their values.
Application code should access the results in the result object by using the DynamicBeans API. For example, suppose the RPC call adds two integers and stores the result as an integer named sum. The application code could obtain the value of sum like this:
Integer sum = (Integer) DynamicBeans.getPropertyValue(getCommandResult.getResults(),"sum");
The DynamicBeans API is recommended because it eliminates the need to convert the object returned from the transport RPC into a generic data format, which requires additional memory and processing time. For example, if a query returns a DOM object, the DynamicBeans API can be used to access the data directly from it, avoiding the need to copy the properties from the DOM object to another object type (such as a Map). RPC implementations are not required to use the context Map. It is included in the CommandResult object to provide a way to store additional information that is not part of the result object.
Implementing the RPC API

As mentioned above, the RPC API is intended to be as generic as possible so implementations can support a wide variety of transports and remote systems. However, this flexibility also puts a lot of burden on the implementer. To simplify the process, the atg.integration package includes basic implementations of the Command and CommandHandler interfaces. Rather than implementing the interfaces directly, you can just extend the BaseCommand and BaseCommandHandler classes. The atg.integrations.BaseCommand class provides an execute() method that implements the logic described in the Command Interface section above. Classes that extend this class must provide their own implementations of the invokeRPC() method. The atg.integrations.BaseCommandHandler class provides an executeCommand() method that implements the logic described in the CommandHandler Interface section above. Classes that extend this class can override the executeCommand() method to do their pre- or postprocessing as needed. Implementing this method can be simplified by having the executeCommand() method of the subclass call the executeCommand() method of the parent class while adding pre- or postprocessing of its own. For example, a CachingCommandHandler class might look like this:
109

} else {
Public class CachingCommandHandler extends BaseCommandHandler { Map sCache = new HashMap(); // Cache of method invocations. Public CommandResult executeCommand(Command pCommand, Object pInput) { if (sCache.containsKey(pInput)) { return sCache.get(pInput);
CommandResult result = super.executeCommand(pCommand, pInput); sCache.put(pInput, result); return result; } } }
For more information about BaseCommand and BaseCommandHandler, see the ATG API Reference.
Exception Handling
The Command.execute(), Command.invokeRPC(), and CommandHandler.executeCommand() methods must throw exceptions of class atg.integration.CommandInvocationException. This exception is intended to wrap any underlying exceptions that might be thrown by a particular transport or remote system. This exception must wrap the underlying exception, rather than copying its message, so that stack trace printouts include the information from the underlying exception. The CommandInvocationException class has two useful subclasses:
atg.integration.CommandTimeoutException can be thrown when an RPC call
times out. This is a special case, since a timeout doesnt indicate whether the RPC call succeeded or not.
atg.integration.InvalidInputException can be thrown if the input object
passed to the Command is invalid.
Executing Commands in Pages

You can use the atg.integrations.MapRPCDroplet servlet bean to execute RPC commands in JavaServer Pages. This servlet bean executes a command and, depending on whether the command is executed successfully, renders either its output open parameter or its error open parameter. If the command is executed successfully, the result output parameter is set to the result of the command, and the output open parameter is rendered. If an exception is thrown, the exception output parameter is set to the exception, and the error open parameter is rendered. The command input parameter takes an object that implements the atg.integrations.Command interface. The inputParameters parameter supplies the inputs to the command as a java.util.Map of parameter name/value pairs. As an alternative to specifying these values in pages, MapRPCDroplet has command and inputParameters properties that you can use to specify these values in the servlet beans properties file.
110
Note, however, that you cannot specify the same parameter both in the properties file and in a page. If you do this, MapRPCDroplet throws a ServletException.
MapRPCDroplet also takes an inputParameterNames parameter that you can use to specify the input names as a list of page parameters, and then use those page parameters to specify the input values. For example: <dsp:param name="inputParameterNames" value="first_name,age"/> <dsp:param name="first_name" value="Bill"/> <dsp:param name="age" value="43"/>
You cannot include both the inputParameters and the inputParameterNames parameter in the same page, or include inputParameterNames in the page if inputParameters is specified in the servlet beans properties file. However, there is a way you can specify default values for the command parameters in the servlet beans properties file, and then optionally override these values in pages. To do this: Use the inputParameters property to specify the command parameters and their default values. In your pages, define page parameters with the same names as the command parameters.
The values specified for the page parameters override the values in the properties file, and are used when the command is invoked. If a command parameter has no corresponding page parameter, the default value from the properties file is used.
Input Parameters
command The command to execute. Must be an instance of a class that implements the atg.integrations.Command interface. This parameter can either be defined in a page or by setting the command property of the servlet bean, but it cannot be defined both ways. inputParameters The inputs to pass to the command, supplied as a java.util.Map of parameter name/value pairs. This parameter can either be defined in a page or by setting the inputParameters property of this servlet bean, but it cannot be defined both ways. inputParameterNames A comma-separated list of command input parameter names. Each name defines a page parameter whose name and value (specified in the page) are used to supply one of the inputs to the command. parameter names Page parameters that correspond to the names of command input parameters specified in inputParameterNames.
Output Parameters
result The result object from the command, if the execution is successful.
111

Open Parameters
exception The exception thrown by the command, if the execution is unsuccessful.
output Rendered if the command is executed successfully. error Rendered if the command throws an exception.
Example
The following example uses inputParameterNames to create a UserId page parameter, and then sets its value to the value of a profile ID. This parameter name/value pair is passed as an input to the command. Depending on whether the command is executed successfully, Dynamo renders either the output open parameter or the error open parameter.
<dsp:droplet bean="/atg/integrations/MapRPCDroplet"> <dsp:param name="command" value="bean:/atg/integrations/jdbc/QueryForUser"/> <dsp:param name="inputParameterNames" value="UserId"/> <dsp:param name="UserId" value="bean:Profile.Id"/> <dsp:oparam name="output"> <p>The user's email address is: <dsp:valueof param="result.emailAddress"/> </dsp:oparam> <dsp:oparam name="error"> <p>Unable to execute query. The following exceptions occurred: <dsp:valueof param="exception"/> </dsp:oparam> </dsp:droplet>
112
Part III: ATG Platform REST Web Services
This section provides information about and instructions for using the ATG platform Representational State Transfer (REST) Web Services. See basic information about using the REST Web Services interface in Using REST Web Services. The REST Web Services provide access to Nucleus components. Nucleus components are server-side JavaBeans and servlets that perform the back-end functionality of a Web applicationfor example, enabling database connectivity, logging, scheduling, and handling HTTP requests. The ATG platform REST Web Services expose methods that get component data and get and set component property values. You cannot use the ATG platform REST Web Services to delete components. See instructions for specific operations in the following sections. Working with Component Properties Invoking Component Methods Invoking Form Handlers Working with Repositories
Note: The ATG platform REST Web Services are not related to the SOAP Web Services described previously in this guide. The REST and SOAP modules do not share any functionality. The two technologies were developed independently and are quite different in their implementations.
113
114
9 Using REST Web Services
This section provides general information about and instructions for using the ATG platform REST Web Services interface. You must do the following before you can use the REST Web Services. 1. 2. 3. Start the REST module on the ATG platform server. See Starting the REST Module. Configure the security settings to give at least one user permission to use REST Web Services. See Security for REST Web Services. Log in to the REST Web Services server and configure your HTTP client software to pass the session ID to the server with each HTTP request. See Logging In.
The following diagram shows components of the REST Web Services interface and the sections of this document that explain them.
1. Starting the REST Module 2. Configuring the REST Server 3. Security for REST Web Services 4. HTTP Requests 5. Input Values 6. Returned Data
115
9 - Using REST Web Services
7. Errors and Exceptions 8. Client Software 9. ATG Client Libraries
Starting the REST module

To use the REST Web Services, include the REST module in your ATG platform server. See information about assembling ATG applications in the ATG Programming Guide. The following example shows a screen from the ATG Configuration and Installation Manager (CIM) that edits the list of modules included in a server. See information about using CIM in the ATG Installation and Configuration Guide.
-------MODULE LIST EDITOR OPTIONS----------------------------------------------enter [h]elp, [m]ain menu, [q]uit to exit
Current Module List: DafEar.Admin, DPS, DSS, Service.SelfService, DAF.Search.Routing, ARF.base, DAF.Search.Base.QueryConsole, REST
*[A] [R] [D] >
Add A Custom Module Remove A Custom Module Done
HTTP Requests
This section provides information about the HTTP requests that you can send to the REST Web Services running on an ATG platform server.
REST Web Services URLs

The URLs for ATG platform REST Web Services are the locations to which you address HTTP requests. URLs are central to REST Web Services and you will access different components and functions of the ATG platform using the specific URL for each one. The application path in the ATG platform REST Web Service URLs starts with /rest/. The application path is the portion of a URL that follows the hostname and port number. For example, you can use the
116
following URL to request the value of the running property of the atg/dynamo/Configuration component.
http://servername:port/rest/bean/atg/dynamo/Configuration/running
The portion of the application path following /rest/ identifies the specific component you are addressing. This part of the URL is based on the component pathnames of Nucleus components and repository items. See information about component paths in the ATG Programming Guide.
Nucleus Components
The URL for addressing a Nucleus component with the REST Web Services 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 invoke methods and get or set property values of Nucleus components. Include 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 Component Properties and Invoking Component Methods.
Repositories
The URL for addressing a repository item with the 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/
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
117

Client Software
See information about performing operations with repositories in Working with Repositories.
You can use any means of transmitting HTTP requests to the ATG platform REST Web Services that you wish. Any client software that is capable of sending and receiving messages via HTTP will be adequate. Select the client software that you use according to the requirements of your environment.
ATG Clients for the REST Web Services

ATG provides two client libraries that you can use to interact with the ATG platform REST Web Services. These clients make the REST Web Services easier to use by hiding all the complexity of creating connections, assembling payloads for requests, and processing responses. See information about the clients in ATG Client Libraries.
Curl Command Line Tool in Documentation Examples

The examples in this document use the Curl command-line tool to send and receive HTTP messages. Curl is shown in these examples because its command-line invocation shows the input and the HTTP activity that takes place when using the ATG platform REST Web Services. See information about the Curl command-line tool at http://curl.haxx.se/. Note: You can use any client software to exchange HTTP messages with the ATG platform REST Web Services. You are not required or encouraged to use the Curl command-line tool. Note: ATG is not associated with the makers of the Curl command-line tool in any way. Find all information about the tool and its makers at http://curl.haxx.se/. The examples in this document include several command-line flags. These flags configure the behavior of the Curl command-line tool as it makes HTTP requests. The flags are included in examples to better show the HTTP requirements of the ATG platform REST Web Services interface and to help you reproduce the examples if you choose to do so. The following example shows a typical invocation of the Curl command-line tool. The components of the command are explained in the table below.
curl -v \ -b cookies.txt \ -X PUT \ -H "Content-Type: application/xml" \ -d "<parameters><middleName>Desire</middleName></parameters>" \ http://servername:port/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/300001
118
Command Component
curl
Explanation Names the program being invoked. The manner in which you invoke the Curl command-line tool depends on the way it has been installed in your environment. Write verbose output while sending and receiving HTTP messages. This option exposes more details of the HTTP transaction. Use cookies stored in the specified file to authenticate the client. This example specifies that cookies are stored in a file named cookies.txt. A session identifier must be stored in the file. When Curl logs into the REST Web Services, the -c cookies.txt instructs it to write the cookies it receives in that file. See Logging In.
-v
-b
-X
Use the specified HTTP method when communicating with the REST Web Services. This example specifies that Curl should use the PUT method. 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. See Setting the Content-Type Value. Include the following content in the message body of the HTTP request. This example includes XML parameters in the message body. The URL of the ATG platform REST Web Service that is used in the example. See REST Web Services URLs.
-H
-d
URL
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 ATG platform REST Web Services. For example, the application server version identifiers shown in the HTTP transaction may not match the application that your ATG platform server uses.
HTTP Methods
The ATG platform REST Web Services support the standard HTTP methods. These methods are described in the following table.
Method GET
Explanation Use this method to return data. Examples of the values you may get are repository item and Nucleus component property values, RQL query results, repository items, and Nucleus components.
119

POST
Use this method to invoke functionality or make changes to your ATG platform server. For example, you may invoke methods, update Nucleus component properties, and create repository items. The REST Web Services server will treat POST requests as different methods if you include certain control parameters. See Handling POST Requests as Other Methods.
PUT
Use this method to make changes to your ATG platform server. For example, you may update repository item and Nucleus component property values.
DELETE
Use this method to remove repository items.
Handling POST Requests as Other Methods

In some situations you may need to submit a POST HTTP request when an operation requires a different method. The REST Web Services server recognizes control parameters that alter the way that it handles POST requests. See information about control parameters in Control Parameters. Use the atg-rest-http-method control parameter to process an HTTP POST request as a GET, PUT, or DELETE request. This allows you to perform operations that require GET, PUT, or DELETE methods even if your client software cannot send HTTP messages with them. For example, you can include message body data with an HTTP POST request but have the server process it as if it were an HTTP GET request.
Logging In
Before you can use the ATG platform 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 will authenticate the user and return a session identifier if the authentication is successful. The procedure for logging in to the REST Web Services server is different for external and internal users. See specific procedures with examples in Logging In as an External User and Logging In as an Internal User.
Handling Session Identifiers

When you successfully log in to the REST Web Services server, it will return a session identifier with its HTTP response. The HTTP client that you use must present that session identifier each time it interacts with the REST Web Services server. One method for handling the session identifier is to allow the server to set it in a cookie file for the client.
120
The specific procedure you use to handle the session identifier depends on the client software you are using. The examples in Logging In as an External User and Logging In as an Internal User show how one HTTP client stores the session identifier in a cookie file.
Logging In as an External User

Invoke the /atg/userprofiling/ProfileServices.loginUser method to log in to the REST Web Services server as an external user. Supply your username and password as functional parameters with the HTTP POST request. Use the positional parameter name arg1 for the username and arg2 for the password. See information about functional parameters and invoking methods in Functional Parameters and Invoking Component Methods.
Success and Failure Responses for External User Log In

If your attempt to log in is successful, the REST Web Services server will return the identifier of the user account in an HTTP response with status code 200 OK. For example, <atgResponse>120001</atgResponse>. If your attempt to log in fails, the server will return a null value in an HTTP response with status code 200 OK. For example, <atgResponse/>. Note: the server returns status code 200 OK in both conditions. Make sure you examine the response value to determine whether an attempt to log in succeeded.
Example of Logging in as an External User

The following example shows an HTTP request to open a REST Web Services session as an external user. The server returns a session identifier in the field labeled JSESSIONID.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2></parameters>" \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Content-Type: application/xml > Content-Length: 71 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
121

< X-ATGGF0Zm9y
* Added cookie JSESSIONID="7978B952714AB08BEB006A348A25ADB0" for * domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=7978B952714AB08BEB006A348A25ADB0; Path=/ Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb 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 myse rver, path /, expire 1290872360 < Set-Cookie: DYN_USER_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e; Expires=Sat, 27Nov-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
Logging In as an Internal User

Invoke the Login operation of the /atg/userprofiling/InternalProfileFormHandler component to log in to the REST Web Services server as an internal user. Supply your username and password as functional parameters with the HTTP POST request. Use the parameter name value.login for the username and value.password for the password. See information about functional parameters and invoking form handler components in Functional Parameters and Invoking Form Handlers . 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.
Success and Failure Responses for Internal User Log In

Make sure you include the atg-rest-return-form-handler-exceptions control parameter when you invoke /atg/userprofiling/InternalProfileFormHandler/login. If you do not use this control parameter, you will not be able to distinguish between a successful log in attempt and one that fails. See Control Parameters. If your attempt to log in is successful, the REST Web Services server will return a response with no exceptions and the HTTP status code 200 OK. For example:
122
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result> </atgResponse>
If your attempt to log in fails, the server will return the exceptions encountered in an HTTP response with status code 200 OK. For example:
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions> <formExceptions> <element>The password is incorrect</element> </formExceptions> </exceptions> <result>true</result> </atgResponse>
Note: the server returns status code 200 OK in both conditions. Make sure you examine the response value to determine whether an attempt to log in succeeded.
Example of Logging in as an Internal User

The following example shows an HTTP request to open a REST Web Services session as an internal user. The server returns a session identifier in the field labeled JSESSIONID.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/json" \ -d "{ value.login=MyInternalUsername , value.password=MyInternalPassword }" \ http://myserver:8280/rest/bean/atg/userprofiling/InternalProfileFormHandler/login? atg-rest-return-form-handler-exceptions=true * About to connect() to myserver port 8280 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8280 (#0) > POST /rest/bean/atg/userprofiling/InternalProfileFormHandler/login?atg-restreturn-form-handler-exceptions=true HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8280 > Accept: */* > Content-Type: application/json > Content-Length: 70 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1
123

path /, expire 0 < X-ATGmNoLzEwLjAg
< X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Added cookie JSESSIONID="09FA8F5B4B8A4C1A1E97480A91BA7EB8" for domain myserver, < Set-Cookie: JSESSIONID=09FA8F5B4B8A4C1A1E97480A91BA7EB8; Path=/ Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAsU2Vhc WyBQbGF0Zm9ybUxpY2Vuc2UvMCBT ZWFyY2hBZG1pbkxpY2Vuc 2UvMCBQdWJsaXNoaW5nTGljZW5zZS8wIEIyQ0xpY2Vuc2UvMCAgXQ== < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Thu, 28 Oct 2010 20:57:22 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions/> <result>true</result> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Logging Out
You can log out to end your ATG platform REST Web Services session. After you log out, no client will be able to perform REST Web Services operations using the session ID that you present with the log out request. Invoke the /atg/userprofiling/ProfileServices.logoutUser method to log out of the REST Web Services server. Use the HTTP POST method. The following example shows an HTTP request to log out of a REST Web Services session.
curl -v -b cookies.txt -X POST \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/logoutUser * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > POST /rest/bean/atg/userprofiling/ProfileServices/logoutUser HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=120001; JSESSIONID=51B1124DFFC8293CF42ACA8AF2D88324; DYN_USE
124
R_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY 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
Control Parameters
Include control parameters with HTTP requests to alter the way that the ATG platform REST Web Services handle them. For example, if you would like the server to include an identifying string in the response you can use the atg-rest-user-input control parameter to specify that identifying string. You can include control parameters either in the URL for the REST Web Service or in the message body of a POST or PUT request. See URL Parameters and Message Body Parameters. Note: Several control parameters have equivalent configuration properties. Set these configuration properties to control the way that REST Web Services are processed by default. See Configuring the REST Server.
Control Parameter Reference

The following table explains the control parameters recognized by the REST Web Services server.
Parameter
atg-rest-appendmulti-values
Explanation Use this parameter to control whether setting a value on a repository item property will add the value to an existing set of values or replace them. This only applies to repository item properties that hold multiple values. See Appending Values to Repository Item Properties.
125

atg-rest-count atg-rest-depth
For requests which return an array or ordered list, adding this parameter with an integer value allows the caller to specify the number of elements to return. Used with atg-rest-index. The number of references to traverse when rendering output. By default it is zero which causes only the top level object to be returned. Use this parameter to specify which form handler values should be processed first. See Form Value Priority. Use this parameter to send the REST Web Server a POST HTTP request but have it process the request as if it used a different HTTP method. For example you can use this control parameter to include message body data in a POST HTTP request but have the server process the request as if it used the GET method. Set the value of this parameter to GET, PUT, or DELETE.
atg-rest-form-tagpriorities atg-rest-http-method
atg-rest-index
Use this parameter to specify the entry in an array or ordered list that will be the starting point when that array or ordered list is returned by the server. Set the value of the parameter to the integer value of the starting position. Use this parameter with atg-rest-count.
atg-rest-input
Use this parameter to override the default input format configured for the server. Set the value of this parameter to json or xml.
atg-rest-json-input
Use this parameter to control whether the REST Web Services server will accept standard JSON markup for setting collection or map values on repository item properties. See JSON Markup Input for Multiple Value Repository Item Properties. Use this parameter to specify the Java method signature when calling an overloaded method. This parameter is only needed if two or more instances of the overloaded method have the same number of arguments.
atg-rest-method
atg-rest-output
Use this parameter to override the default output format configured for the server. See Choosing Output Markup. Set the value of this parameter to json or xml. Use this parameter to apply property filtering to individual REST Web Services Requests. See Filtering for One Request. Use this parameter to specify that the REST Web Services server should return exceptions it encounters when invoking form handlers in the HTTP response. See Returning Form Handler Exceptions.
atg-rest-propertyfilters atg-rest-returnform-handlerexceptions
126
atg-rest-returnform-handlerproperties atg-rest-rql atg-rest-simpleresponse-codes atg-rest-transient
Use this parameter to specify that the REST Web Services server should return the properties of the form handler objects it invokes in the HTTP response. See Returning Form Handler Properties. Include RQL query strings in this parameter. See Performing RQL Queries. Include this parameter to cause the server to return OK (200) for success rather than CREATED (201) or GONE (410). Use this parameter to create transient repository items. Include the parameter with the value true with a REST Web Services request to create a repository item. See Transient Items. Use this parameter to specify an identifying string that the REST Web Services server will include in the HTTP response. See Identifying a Response.
atg-rest-user-input
Functional Parameters
Functional parameters provide data that is required by the ATG platform REST Web Services operation you are performing. For example, if you are setting a property value, the new value is a functional parameter of the operation. You can include functional parameters either in the URL for the REST Web Service or in the message body of a POST or PUT request. See URL Parameters and Message Body Parameters. The functional parameters you provide for a REST Web Services operation depend on the nature of that operation. When invoking a method, you may supply arguments to it. When invoking a form handler, you will supply the form field values. When setting a repository item property value, you will supply the new value. The functional parameters for each operation are explained in the procedures for those operations. See operational procedures in the following sections. Working with Component Properties Invoking Component Methods Working with Repositories
Positional Parameters
Some ATG platform REST Web Services operations require parameters that are not named. For example, if you invoke the loginUser method of the /atg/userprofiling/ProfileServices component you must pass in two positional arguments. The first is the login value for a user and the second is the password value for that user. The 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.
127
The URL parameters in the following REST Web Services URL contain positional parameters that are passed to the loginUser method.
http://servername:port/rest/bean/atg/userprofiling/ProfileServices/loginUser?arg1= MyUsername&arg2=MyPassword
The 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 Component Methods.
public String loginUser(String pLogin, String pPassword) throws ServletException
URL Parameters
You can include control and functional parameters in the URL for ATG platform REST Web Services. Use standard URL query string syntax and URL encoding if needed. The following example shows a URL with two functional parameters and a control parameter.
http://servername:port/rest/bean/atg/userprofiling/ProfileServices/loginUser?arg1= MyUsername&arg2=MyPassword&atg-rest-user-input=MyMessageId
Message Body Parameters

You can include control and functional parameters in the HTTP message body of an ATG platform REST Web Services request. The following HTTP request includes two functional parameters and a control parameter in its message body. The content in the message body is specified by the -d flag in this Curl command. See Curl Command Line Tool in Documentation Examples.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2><atg-rest-userinput>MyMessageId</atg-rest-userinput></parameters>" http://servername:8080/rest/bean/atg/userprofiling/ProfileSer vices/loginUser
128
The 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. See Setting the Content-Type Value. XML, see XML Parameter Markup. JSON, see JSON Parameter Markup. URL query string, see URL Query String Parameter Markup.
The 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.
Setting the Content-Type Value

Set the Content-Type value when you send an HTTP message with parameters in its message body. The ATG platform REST Web Services server uses this value to determine how to interpret the parameters. If you do not include the Content-Type or include a value that doesnt match the markup of your parameters, the server will ignore the message body. Use one of the following Content-Type values to specify the markup of the parameters in a message body.
Content-Type: application/xml Content-Type: application/json Content-Type: application/x-www-form-urlencoded
The following example shows an HTTP request that sets its Content-Type to application/xml.
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>MyUsername</arg1><arg2>MyPassword</arg2><atg-rest-userinput>MyMessageId</atg-rest-userinput></parameters>" http://servername:8080/rest/bean/atg/userprofiling/ProfileSer vices/loginUser * About to connect() to servername port 8080 (#0) * Trying 12.34.567.890... connected * Connected to servername (12.34.567.890) port 8080 (#0) > POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: servername:8080 > Accept: */* > Content-Type: application/xml > Content-Length: 125
129
XML Parameter Markup

You can use eXtensible Markup Language (XML) to format parameters in the message body of an ATG platform REST Web Services request. Enclose all message body content in a parameters element as shown in the example below. Include each parameter in a separate child element. Use the name of the parameter as its element name. For positional parameters that do not have names, use the arg1, arg2, arg3 convention to name their elements. See Positional Parameters.
<parameters> <arg1>MyUsername</arg1> <arg2>MyPassword</arg2> <atg-rest-user-input>MyMessageId</atg-rest-user-input> </parameters>
Make sure that you specify Content-Type: application/xml in the HTTP message. See Setting the Content-Type Value.
JSON Parameter Markup

You can use JavaScript Object Notation (JSON) to format parameters in the message body of an ATG platform REST Web Services request. Enclose the parameters in standard JSON format as shown in the example below. Include each parameter in a separate name and value pair. Use the name of the parameter as the name for the pair. For positional parameters that do not have names, use the arg1, arg2, arg3 convention as the names for the pairs. See Positional Parameters.
{ "arg1": "MyUsername", "arg2": "MyPassword", "atg-rest-user-input": "MyMessageId" }
Make sure that you specify Content-Type: application/json in the HTTP message. See Setting the Content-Type Value. The following example shows numeric parameter input using JSON markup.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/json" -d "{ "arg1" : 4 }" \ http://myserver:8080/rest/bean/atg/rest/Configuration/maxDepthAllowed
130
URL Query String Parameter Markup

You can use the URL query string format to include parameters in the message body of an ATG platform REST Web Services request. Include the parameters in standard URL query string format as shown in the example below. Include each parameter in a separate name and value pair. Use the name of the parameter as the name for the pair. For positional parameters that do not have names, use the arg1, arg2, arg3 convention as the names for the pairs. See Positional Parameters.
arg1=MyUsername&arg2=MyPassword&atg-rest-user-input=MyMessageId
URL encode any special URL characters in the parameter values. Make sure that you specify ContentType: application/x-www-form-urlencoded in the HTTP message. See Setting the Content-Type Value.
Input Values
This section provides information about the way the ATG platform REST Web Services server expects to receive parameter values.
Primitive Values in Input

Format primitive values as shown in the following table.
Value Type String Number Boolean
Values Accepted A sequence of characters. For example, MyUsername. An integer or decimal number. For example, 123 or 123.456.
true and false
Multiple Values in Input

The REST Web Services server will accept map and collection input when you set the values of properties that accept multiple values. Format array, collection, and map values as shown in the following table.
131

Value Type Array Collection
Format <array-element-class>:[value1,value2,...,valueN] For example:

java.lang.String:[foo,bar,baz]
<collection-container-class>:<element-class>:[value1,value2,...,valueN] For example:

java.util.ArrayList:java.lang.String:[foo,bar,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=soccer,bar=baseball,baz=football]
When you set the value of a non-repository, Nucleus component property, the REST Web Services server will replace all values with any new values that you set. To append a value to an existing collection, you must supply all the existing values along with the new values. You can configure the way the REST Web Services server appends or replaces multiple values in a repository item property. See Appending Values to Repository Item Properties and Replacing Multiple Values in a Repository Item Property. The following example shows a REST Web Services request that appends a value to a non-repository component property. It includes all existing values in the property along with the new value. To remove a value, make a similar request that includes only the values that you wish to remain in the property.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ d "<parameters><arg1>java.util.ArrayList:java.lang.String:["Existing String in the Collection", "New String for the Collection"]</arg1></parameters>" \ http://myserver:8080/rest/bean/atg/Component/myCollectionProperty
Appending Values to Repository Item Properties

To append data to a repository item property that holds multiple values, set the new value as you would for a single value property. See Setting Repository Item Properties. The following example adds two repository item reference values to a repository item property that can hold multiple values. Any existing values in that property will remain there.
132
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>/atg/commerce/gifts/Giftlists/giftlist/gl40050,/atg/commerce/gifts/Giftlists/giftlist/gl40052</arg1></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130001/giftlists
Note: The 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-restappend-multi-values control parameter to true for each REST Web Services request that should append the new value. See appendMultiValuesByDefault.
Replacing Multiple Values in a Repository Item Property

To replace all the existing values in a repository item property that holds multiple values, include the atgrest-append-multi-values control parameter with your REST Web Services request. Set the value of
the control parameter to false. Note: You can only use the rest-append-multi-values control parameter with repository item properties. It does not affect the way you can update non-repository properties. The following example replaces all the values that are currently in a repository item property that holds multiple values. Only the repository item reference that is in the functional parameter will remain in the property.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>/atg/commerce/gifts/Giftlists/giftlist/gl40049</arg1></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130001/giftlists?atg-rest-append-multi-values=false
JSON Markup Input for Multiple Value Repository Item Properties

If you are setting multiple values in a repository item property, you can use standard JSON markup for the collection or map value. Include the atg-rest-json-input with your REST Web Service request and set its value to true. You can include JSON markup for multiple values in any input format. The following example shows a REST Web Services request that includes a JSON collection in an XML message body parameter.
curl.exe -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>[ "/atg/commerce/gifts/Giftlists/giftlist/gl40050", "/atg/commerce/gifts/Giftlists/gift-
133

HTTP Status Codes
list/gl40052" ]</arg1></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130001/giftlists?atg-rest-json-input=true
The ATG platform REST Web Services server returns an HTTP status code to indicate the result of each request. The HTTP status codes that it returns are: 200 (OK) - The request was processed successfully. This does not mean that it had the result you intended. See information about how to determine success or failure in the instructions for specific operations. 201 (Created) - Returned only for POST requests that create repository items. The request was successful and the repository item was created. 400 (Bad Request) - The request could not be completed because the request URL and/or parameters were improperly formatted. 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 writable via the filtering configuration. 404 (Not Found) - The request could not be completed because it was made for a resource that does not exist. 410 (Gone) - Returned only for DELETE requests that remove repository items. The request was successful and the repository item was deleted. 500 (Internal server error) - The request could not be completed because an unexpected exception occurred.
Returned Data
The ATG platform REST Web Services server will return the results of the operations you perform in an HTTP response message body. The contents of the returned data depend on the operation you are performing. This section explains the formats that the server will return data in. It also explains how to configure the server to return data in the manner you choose.
Choosing Output Markup

The ATG platform REST Web Services server can return output data in either JavaScript Object Notation (JSON) or eXtensible Markup Language (XML) format. It will enclose all returned data in a JSON object with the name atgResponse or an atgResponse XML element.
134
The following example shows JSON output markup.
{"atgResponse": "280001"}
The following example shows XML output markup.
<atgResponse>280001</atgResponse>
Default Output Markup

Configure your ATG platform REST Web Server to return output data in the format you choose. The default output format of the server is controlled by its /atg/rest/Configuration/defaultOutputCustomizer property. For JSON output, set the property to /atg/rest/output/JSONOutputCustomizer. For XML output, set the property to /atg/rest/output/XMLOutputCustomizer.
The server will return data in its default output format if you do not specify the output format for an individual request. See Specifying Output Markup for One Request.
Specifying Output Markup for One Request

You can choose either JSON or XML for the returned data of a single ATG platform REST Web Services request. The output format you specify for an individual request will override the default output markup setting. To specify the output format for an individual REST Web Services request, include the atg-rest-output control parameter with that request. Set the value of atg-rest-output to either json or xml. See Control Parameters. The following example shows a 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, multivalued elements are surrounded by brackets, and references to repository items are URLs to the item referenced. Note that multivalued elements will be URLs also, but in this example, the abcArray has been expanded.
{ "myClass": "class atg.rest.processor.MockObject",
135

"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</atgRestCompone ntPath> </organizationPathCache> <rootOrganizationPrimaryKey>root</rootOrganizationPrimaryKey> [Additional property values omitted to save space] <roles> <element> -RepositoryItemGroupRole: --> name: Young --> primary key: Young__grouprole </element> <element> -RepositoryItemGroupRole: --> name: WomenOnly --> primary key: WomenOnly__grouprole </element> <element> -RepositoryItemGroupRole: --> name: Fashionista --> primary key: Fashionista__grouprole </element> <element> -RepositoryItemGroupRole: --> name: MenOnly --> primary key: MenOnly__grouprole </element>
136
<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 an ATG platform 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 REST Web Service request. To specify the identifying string for a 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 Control Parameters. The following example shows a REST Web Services request that includes the atg-rest-user-input control parameter.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-userinput=MyMessageId001 * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/bean/atg/dynamo/Configuration/httpPort?atg-rest-userinput=MyMessageId001 HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: JSESSIONID=AD84270CB05CC0960580D1B875595822 > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9yb UxpY2Vuc 2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ== < Content-Type: application/json;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 22 Oct 2010 16:36:07 GMT
137

< {
"atg-rest-response": {"httpPort": 8080}, "atg-rest-user-input": "MyMessageId001" }* Connection #0 to host myserver left intact * Closing connection #0
Multiple Values in Output

This section provides information about the format of collection and map values in response messages from the REST Web Services server.
Expanding Multiple Values and Complex Objects

The REST Web Services server returns multiple-values and complex objects as REST paths by default. Include the atg-rest-show-rest-paths control parameter to expand these values in the response you receive. Set the value of the control parameter to true. If you set atg-rest-show-rest-paths to false, the REST response will include expanded data for nested properties down to the level specified by the atg-rest-depth control parameter. See Return Depth. You can configure the default setting for atg-rest-show-rest-paths. See showRestPaths JSON and showRestPaths XML. The example below shows a REST path in the creditCards property. The example that follows it shows the effect of the atg-rest-show-rest-paths control parameter.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130001/ * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/ HTT P/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_USE R_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="A2C79A00F7194A1F113604FD1C4BE7DD" for domain myserve r, path /, expire 0 < Set-Cookie: JSESSIONID=A2C79A00F7194A1F113604FD1C4BE7DD; Path=/
138
< X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2 Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 05 Nov 2010 21:50:44 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> [Additional property values omitted to save space] <creditCards>http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapt erRepository/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 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/us er/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_USE R_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 myserve r, path /, expire 0 < Set-Cookie: JSESSIONID=9D730DE9D4A7C250994F20363ACC3FA6; Path=/ < X-ATG-
139

GF0Zm9ybU <
Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb 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</atgRest ComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10003</atgRestRepositoryId> </value> </element> <element> <key>MyCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository</atgRest ComponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10001</atgRestRepositoryId> </value> </element> </creditCards> [Additional property values omitted to save space] </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Collection Values in Output

The REST Web Services server will return each element in a property value of class java.utils.Collection as shown in the examples below.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileUserDirectory/roles
140
* About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/bean/atg/userprofiling/ProfileUserDirectory/roles HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140003; JSESSIONID=9B95CAFAA8B94A05C46488E482A91543; DYN_USE R_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="6F710DD421CDBB1C0A092133210E7A0E" for * domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=6F710DD421CDBB1C0A092133210E7A0E; Path=/ < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9yb UxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Wed, 03 Nov 2010 15:05:19 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <roles> <element> -RepositoryItemGroupRole: --> name: Young --> primary key: Young__grouprole </element> -<element> RepositoryItemGroupRole:
--> name: WomenOnly --> primary key: WomenOnly__grouprole </element> -<element> RepositoryItemGroupRole:
--> name: Fashionista --> primary key: Fashionista__grouprole </element> -<element> RepositoryItemGroupRole:
--> name: MenOnly --> primary key: MenOnly__grouprole </element> -<element> RepositoryItemGroupRole:
--> name: ThirtySomethings --> primary key: ThirtySomethings__grouprole </element> </roles></atgResponse>* Connection #0 to host myserver left intact * Closing connection #0
141

{"roles": [ "\n-"\n-"\n-"\n-"\n-]}
The following example shows the same property value in JSON format.
RepositoryItemGroupRole:\n--> name: Young\n-RepositoryItemGroupRole:\n--> name: WomenOnly\n-RepositoryItemGroupRole:\n--> name: Fashionista\n-RepositoryItemGroupRole:\n--> name: MenOnly\n-RepositoryItemGroupRole:\n--> name: ThirtySomethings\n--
> primary key: Young__grouprole\n", > primary key: WomenOnly__grouprole\n", > primary key: Fashionista__grouprole\n", > primary key: MenOnly__grouprole\n", > primary key: ThirtySomethings__grouprole\n"
Map Values in Output

The REST Web Services server will return each element in a property value of class java.utils.Map as shown in the examples below.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130001/creditCards * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/cred itCards 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_USE R_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="F60503E5A6051C18D119B6CE470F9591" for domain myserve r, path /, expire 0 < Set-Cookie: JSESSIONID=F60503E5A6051C18D119B6CE470F9591; Path=/ < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2V uc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Wed, 03 Nov 2010 16:12:57 GMT
142
< <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <creditCards> <element> <key>MyOtherCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapter Repository/credit-card/usercc10003</value> </element> <element> <key>MyCard</key> <value>http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapter Repository/credit-card/usercc10001</value> </element> </creditCards> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
The following example shows the same property value in JSON format.
{"creditCards": { "MyCard": "http://myserver:8080/rest/repository/atg/userprofilin g/ProfileAdapterRepository/creditcard/usercc10001", "MyOtherCard": "http://myserver:8080/rest/repository/atg/userpr ofiling/ProfileAdapterRepository/credit-card/usercc10003" }}
Return Depth
You can control the number of nested levels of property information that the 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 REST Web Services server. See maxDepthAllowed. 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/ProfileAdapter Repository/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:
143

<creditCards> <element> <value> mponentPath>
<key>MyOtherCard</key> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository</atgRestCo <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10003</atgRestRepositoryId> </value> </element> <element> <key>MyCard</key> <value> <atgRestComponentPath>/atg/userprofiling/ProfileAdapterRepository</atgRestCo mponentPath> <atgRestItemDescriptor>credit-card</atgRestItemDescriptor> <atgRestRepositoryId>usercc10001</atgRestRepositoryId> </value> </element> </creditCards>
Errors and Exceptions

If an error or exception occurs when you use the ATG platform REST Web Services, the server will indicate the nature of the problem in the HTTP response status code. See HTTP Status Codes.
Problems Performing Operations

If the REST Web Services server can process the input in your request but it encounters problems performing an operation it will return HTTP status code 400 Bad Request. The following example shows an exception that has been returned by the REST Web Services server. HTTP status code 400 Bad Request indicates that the server cannot perform the requested action because of a problem with the input provided. The server includes the name of the exception (atg.beans.PropertyNotFoundException) in the message body of the response.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration/fakeProperty * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/bean/atg/dynamo/Configuration/fakeProperty HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080
144
> Accept: */* > Cookie: JSESSIONID=67B1EAF58CC556CE7C628CDE6F395FB4 > < HTTP/1.1 400 Bad Request < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9yb Uxp Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ== < Content-Type: text/html;charset=utf-8 < Content-Length: 1585 < Date: Fri, 22 Oct 2010 19:48:53 GMT < Connection: close < <html><head><title>JBoss Web/2.1.3 - Error report</title><style><!--H1 {fontfamily:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;fontsize:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;backgroundcolor:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sansserif;color:white;background-color:#525D76;font-size:14px;} BODY {fontfamily:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {fontfamily:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {fontfamily:Tahoma,Arial,sans-serif;background:white;color:black;fontsize:12px;}A {color: black;}A.name {color : black;}HR {color : #525D76;}-></style> </head><body><h1>HTTP Status 400 atg.beans.PropertyNotFoundException: Can't find property named: fakeProperty in c lass: atg.service.dynamo.DAFConfiguration Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration</h1><HR size="1" noshade="noshade">< p><b>type</b> Status report</p><p><b>message</b> <u>atg.beans.PropertyNotFoundExce ption: Can't find property named: fakeProperty in class: atg.service.dynamo.DAFCon figuration Can't find property named: fakeProperty in class: atg.service.dynamo.DA FConfiguration</u></p><p><b>description</b> <u>The request sent by the client was syntactically incorrect (atg.beans.PropertyNotFoundException: Can't find property named: fakeProperty in class: atg.service.dynamo.DAFConfiguration Can't find prope rty named: fakeProperty in class: atg.service.dynamo.DAFConfiguration).</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3> </body></html>* Closing connection #0
Problems Processing a Request

If the REST Web Services server cannot process the input in your request it will return HTTP status code 500 Internal Server Error. The following example shows an exception that has been returned by the REST Web Services server. HTTP status code 500 Internal Server Error indicates that the server cannot process the request because of a problem interpreting the input. The server includes the name of the exception (org.dom4j.DocumentException) in the message body of the response.
145
curl -v -c cookies.txt -X POST \ -H "Content-Type: application/xml" -d "This is not XML." \ http://myserver:8080/rest/bean/atg/userprofiling/ProfileServices/loginUser * About to connect() to myserver port 8080 (#0) Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > POST /rest/bean/atg/userprofiling/ProfileServices/loginUser HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Content-Type: application/xml > Content-Length: 16 > < HTTP/1.1 500 Internal Server Error < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Added cookie JSESSIONID="24C3CC9056EA3A1B62DD2002DEDFAA7F" for domain myserver, path /, expire 0 < Set-Cookie: JSESSIONID=24C3CC9056EA3A1B62DD2002DEDFAA7F; Path=/ < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2Vuc2U vMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: text/html;charset=utf-8 < Content-Length: 1776 < Date: Wed, 27 Oct 2010 18:15:29 GMT < Connection: close < <html><head><title>JBoss Web/2.1.3 - Error report</title><style><!--H1 {fontfamily:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;fontsize:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;backgroundcolor:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sansserif;color:white;background-color:#525D76;font-size:14px;} BODY {fontfamily:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {fontfamily:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {fontfamily:Tahoma,Arial,sans-serif;background:white;color:black;fontsize:12px;}A {color: black;}A.name {color : black;}HR {color : #525D76;}-></style> </head><body><h1>HTTP Status 500 org.dom4j.DocumentException: Error on line 1 of document f document : Content is not allowe d in prolog. Nested exception: Content is not allowed in prolog. Error on line 1 o : Content is not allowed in prolog. Nested exception: Content is not a llowed in prolog.</h1><HR size="1" noshade="noshade"><p><b>type</b> Status report< /p><p><b>message</b> <u>org.dom4j.DocumentException: Error on line 1 of document : Content is not allowed in prolog. Nested exception: Content is not allowed in pr olog. Error on line 1 of document : Content is not allowed in prolog. Nested exce ption: Content is not allowed in prolog.</u></p><p><b>description</b> <u>The serve r encountered an internal error (org.dom4j.DocumentException: Error on line 1 of d ocument : Content is not allowed in prolog. Nested exception: Content is not allo
146
wed in prolog. Error on line 1 of document
: Content is not allowed in prolog. Ne
sted exception: Content is not allowed in prolog.) that prevented it from fulfilli ng this request.</u></p><HR size="1" noshade="noshade"><h3>JBoss Web/2.1.3</h3></b ody></html>* Closing connection #0
147
148
10 Working with Component Properties
This section provides instructions for ATG platform REST Web Services operations involving Nucleus component properties.
Getting Component Properties

To get the value of a Nucleus component property, send a REST Web Services request as described in the following table.
Request Component HTTP Method Functional Parameters URL
Value GET None Include the component pathname in the application path after /rest/bean/. Include the name of the property at the end of the path. See Nucleus Components. To get the values of all properties of a component, do not include a property name at the end of the path.
The following example shows a REST Web Services request that returns the value of the atg/dynamo/Configuration.httpPort property.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration/httpPort * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/bean/atg/dynamo/Configuration/httpPort HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: JSESSIONID=8DC60C0801D934F472BD9BE8A15A54F9
149
10 - Working with Component Properties

> < HTTP/1.1 200 OK < X-ATGUxp
< Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Version: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9yb Y2Vuc2UvMCBTZWxmU2VydmljZUxpY2Vuc2UvMCAgXQ== < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Mon, 25 Oct 2010 21:29:05 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <httpPort>8080</httpPort> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
The following example shows a REST Web Services request that returns all the properties of a Nucleus component.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/bean/atg/dynamo/Configuration
Setting Component Properties

To set the value of a Nucleus component property, send a REST Web Services request as described in the following table.
Request Component HTTP Method Functional Parameters
Value POST or PUT Include the new value for the property. Use the positional parameter name arg1 for the value. See Positional Parameters.
URL
Include the component pathname in the application path after /rest/bean/. Include the name of the property at the end of the path. See Nucleus Components.
150
The following example shows a REST Web Services request that sets the value of the atg/userprofiling/passwordchecker/PasswordRuleChecker.enabled property.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>false</arg1></parameters>" \ http://myserver:8080/rest/bean/atg/userprofiling/passwordchecker/PasswordRuleCheck er/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 HT TP/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-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxTZXJ2aWNlLzEwLjAsQ0FGLzEwLjAgWyBQbGF0Zm9yb Uxp 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
151
152
11 Invoking Component Methods
To invoke a Nucleus component method, send a REST Web Services request as described in the following table.
Value POST Include any arguments to the method as positional parameters. The name of the parameter for the first argument is arg1. The name of the parameter for the second argument is arg2. Continue this naming pattern for any further arguments. See Positional Parameters. Include the component pathname in the application path after /rest/bean/. Include the name of the method at the end of the path. See Nucleus Components.
URL
The following example shows a REST Web Services request that invokes the /atg/commerce/order/OrderManager.getOrderCountForProfile method. The method takes a user identifier as its argument and it returns an integer value.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>130001</arg1></parameters>" \ http://myserver:8080/rest/bean/atg/commerce/order/OrderManager/getOrderCountForPro file * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > POST /rest/bean/atg/commerce/order/OrderManager/getOrderCountForProfile HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=120001; JSESSIONID=7C4C04BFDA404FA7D9443A820F32BE0D; DYN_USE R_CONFIRM=bca3eb6c2cdeb0e4a625c7165a088e2e > Content-Type: application/xml > Content-Length: 44
153
11 - Invoking Component Methods

> < HTTP/1.1 200 OK < X-ATG-
< Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2Vuc2Uv MCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Wed, 27 Oct 2010 17:17:33 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>2</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
154
11 - Invoking Component Methods
12 Invoking Form Handlers
To invoke a Nucleus form handler, send a REST Web Services request as described in the following table.
Value POST Submit the required property values of the form as functional parameters. Name each parameter with the property name it corresponds to. See Submitting Form Values. Include the component pathname in the application path after /rest/bean/. Include the name of the form handler operation at the end of the path. See Nucleus Components.
URL
The following example shows a 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.co nfirmPassword":"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_USE R_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b
155
12 - Invoking Form Handlers

> < HTTP/1.1 200 OK < X-ATG-
> Content-Type: application/json > Content-Length: 147
< Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2 Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= * Replaced cookie DYN_USER_ID="140003" for domain myserver, path /, expire 1291317 542 < Set-Cookie: DYN_USER_ID=140003; Expires=Thu, 02-Dec-2010 19:19:02 GMT; Path=/ * Replaced cookie DYN_USER_CONFIRM="1231cf3e7573bf936dbd29dbbbfe150b" for domain m yserver, path /, expire 1291317542 < Set-Cookie: DYN_USER_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b; Expires=Thu, 02Dec-2010 19:19:02 GMT; Path=/ < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Tue, 02 Nov 2010 19:19:02 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>true</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Submitting Form Values

When you invoke a form handler, you must present it with a set of values as functional parameters. These values are the data that would be submitted in form fields if the form handler were being invoked from a user interface. Different types of form handlers require different parameters depending on the function they perform. See more information about form handlers in the ATG Page Developers Guide. For example, the /atg/store/profile/RegistrationFormHandler form handler requires a
java.util.Dictionary property named value that holds a set of dictionary fields. The fields in the
dictionary property hold the values that would be entered in user interface fields on a registration form. To invoke the /atg/store/profile/RegistrationFormHandler form handler, you must include a functional parameter for value.email, value.password, value.confirmPassword, value.firstName, and value.lastName. The following JSON data contains the functional parameters required by the
/atg/store/profile/RegistrationFormHandler form handler.
{ "value.email":"sheroux@example.com", "value.password":"mypassword", "value.confi rmPassword":"mypassword", "value.firstName":"Severe", "value.lastName":"Heroux" }
156
Returning Form Handler Exceptions

Include the atg-rest-return-form-handler-exceptions control parameter with a REST Web Services request to return form handler exceptions in the HTTP response from the server. Set the value of the control parameter to true. The following example shows the response to a REST Web Services request to invoke /atg/userprofiling/InternalProfileFormHandler/login. The response includes an exceptions element that contains information about the exception that occurred.
<atgResponse> <class>class atg.rest.processor.BeanProcessor$FormHandlerExceptions</class> <exceptions> <formExceptions> <element>Missing value for the login property</element> </formExceptions> </exceptions> <result>true</result> </atgResponse>
The following example shows the response to a successful 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 REST Web Services request, the class element in the atgResponse will contain the following value: class atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Form Handler Properties.
Returning Form Handler Properties

Include the atg-rest-return-form-handler-properties control parameter with a REST Web Services request to return the property values of the form handler component. The REST Web Services server will include the property values in a component element in the HTTP response. Set the value of the control parameter to true.
157

<atgResponse> <component>
The following example shows the response to a 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.
<class>class atg.rest.processor.BeanProcessor$FormHandlerProperties</class> <absoluteName>/atg/dynamo/servlet/pipeline/RequestScopeManager/RequestScope409/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/RequestSc opeManager/RequestScope409/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 REST Web Services request, the class element in the atgResponse will contain the following value: class atg.rest.processor.BeanProcessor$FormHandlerPropertiesAndExceptions. See Returning Form Handler Exceptions.
Form Value Priority

Specify the order in which form values are processed using the atg-rest-form-tag-priorities control parameter. Set the value of the control parameter to a JSON object that assigns an integer value to any of the form values that you wish to prioritize. Higher priority numbers are processed first. Values that you do not prioritize are assigned the priority zero. The following example specifies that the value.password field should be processed before any other field.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/json" \ d "{ "value.email": "sheroux@example.com", "value.password": "mypassword", "value. confirmPassword": "mypassword", "value.firstName": "Severe", "value.lastName": "He roux", "atg-rest-form-tag-priorities": { "value.password": 10 } }" \ http://myserver:8080/rest/bean/atg/store/profile/RegistrationFormHandler/create
158
13 Working with Repositories
This section provides instructions for ATG platform REST Web Services operations involving repositories. A repository item is a JavaBean component that implements atg.repository.RepositoryItem or one of its sub-interfaces, and corresponds to the smallest uniquely identifiable entity in the underlying data store. Each repository item is composed of named properties that store the items datafor example, id, firstName, and lastName.
Listing Repository Items

To list the items of a type in a repository, send a REST Web Services request as described in the following table.
Value GET None 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 REST Web Services request that lists the repository items of the user item type in the atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080
159
13 - Working with Repositories

> Accept: */* > < HTTP/1.1 200 OK < X-ATG-
> Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4; DYN_USE R_CONFIRM=2a952017db56aab256c7e7077bf1feec
< Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2Vuc 2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 29 Oct 2010 16:27:49 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <user> <element>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/se-570040</element> <element>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/120001</element> <element>http://myserver:8080/rest/repository/atg/userprofiling/ ProfileAdapterRepository/user/140001</element> </user> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Retrieving a Repository Item

To list the properties of a repository item, send a REST Web Services request as described in the following table.
Value GET None 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.
160
The following example shows a REST Web Services request that lists the properties of a specific repository item of the user item type in the /atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130001/ * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/ HTT P/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4; DYN_USE R_CONFIRM=2a952017db56aab256c7e7077bf1feec > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2Vuc 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
161

Retrieving a Specific Property

To retrieve a specific property of a repository item, send a REST Web Services request as described in the following table.
Value GET None 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 REST Web Services request that returns the lastPurchaseDate property of a specific repository item of the user item type in the atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130001/lastPurchaseDate * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130001/last PurchaseDate HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140001; JSESSIONID=46E252A84E611BCD06710FD6A0FBA5A4; DYN_USE R_CONFIRM=2a952017db56aab256c7e7077bf1feec > < HTTP/1.1 200 OK < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 * Replaced cookie JSESSIONID="A8D99275B90B200E0913A8831E77A9F4" for domain myserve r, path /, expire 0 < Set-Cookie: JSESSIONID=A8D99275B90B200E0913A8831E77A9F4; Path=/ < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybUxpY2Vuc 2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked
162
< Date: Fri, 29 Oct 2010 19:42:35 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <lastPurchaseDate>2010-10-27</lastPurchaseDate> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Performing RQL Queries

To perform a Repository Query Language (RQL) query, send a REST Web Services request as described in the following table. See information about repository queries in ATG Repository Guide.
Value GET 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 REST Web Services request that performs an RQL query. It returns the first four items of item type product in the /atg/commerce/catalog/ProductCatalog repository.
curl -v -b cookies.txt -X GET \ http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCatalog/product?a tg-rest-rql=ALL+RANGE+%2B4 * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > GET /rest/repository/atg/commerce/catalog/ProductCatalog/product?atg-restrql=ALL+RANGE+%2B4 HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */*
163

> < HTTP/1.1 200 OK < X-ATG-
> Cookie: DYN_USER_ID=140003; JSESSIONID=0D62D5F5145D6A1E7A2EDBC669F3BA0F; DYN_USE R_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b
< Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 Version: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9ybU xpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Fri, 29 Oct 2010 21:33:00 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse> <product> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCata log/product/xprod2022</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCata log/product/xprod1064</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCata log/product/xprod2024</element> <element>http://myserver:8080/rest/repository/atg/commerce/catalog/ProductCata log/product/xprod1066</element> </product> </atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Note: You can include the atg-rest-rql functional parameter in the message body of a POST HTTP request if you prefer not to URL encode your RQL queries. Use the atg-rest-view control parameter to instruct the REST Web Services server to handle your POST request as a GET request. See Handling POST Requests as Other Methods. Note: Do not include parameters in the RQL queries that you perform via the REST Web Services. Make sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL queries in the ATG Repository Guide.
Adding a Repository Item

To add a repository item, send a REST Web Services request as described in the following table.
164
Value POST Include all required property values for the new repository item as functional parameters with the REST Web Services request. 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.
URL
The following example shows a REST Web Services request that creates a new repository item in the /atg/userprofiling/ProfileAdapterRepository repository. The returned data includes all the property values for the new item.
curl -v -b cookies.txt -X POST -H "Content-Type: application/xml" \ d "<parameters><login>rbriere</login><lastName>Briere</lastName><firstName>Roland< /firstName><email>rbriere@example.com</email><password>mypassword</password></para meters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > POST /rest/repository/atg/userprofiling/ProfileAdapterRepository/user HTTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140003; JSESSIONID=F9C672B8E52D2033A1B70C4EE225577F; DYN_USE R_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > Content-Type: application/xml > Content-Length: 168 > < HTTP/1.1 201 Created < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1 < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9 ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Mon, 01 Nov 2010 17:35:29 GMT < <?xml version="1.0" encoding="UTF-8"?>
165

<atgResponse>
<repositoryId>130030</repositoryId> <securityStatus>4</securityStatus> [Additional property values omitted to save space] <lastPurchaseDate/> <lastName>Briere</lastName> <gender>unknown</gender> <salePriceList/> <categoryLastBrowsed/> [Additional property values omitted to save space] <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/us er?atg-rest-transient=true
Setting Repository Item Properties

To update properties of a repository item, send a REST Web Services request as described in the following table.
166
Value PUT Include the new values for each property you are updating as functional parameters with the REST Web Services request. 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.
URL
The following example shows a 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/ProfileAdapterRepository/us er/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_USE R_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 myserve r, path /, expire 0 < Set-Cookie: JSESSIONID=6A9888BA9F4035AF606AE7E40A435451; Path=/ < X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm 9ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked
167

<
< Date: Mon, 01 Nov 2010 19:40:41 GMT <?xml version="1.0" encoding="UTF-8"?> <atgResponse>true</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
Deleting a Repository Item

To delete a specific repository item, send a REST Web Services request as described in the following table.
Value DELETE Include the new values for each property you are updating as functional parameters with the REST Web Services request. 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.
URL
The following example shows a REST Web Services request that deletes an existing repository item in the /atg/userprofiling/ProfileAdapterRepository repository.
curl -v -b cookies.txt -X DELETE \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/us er/130037 * About to connect() to myserver port 8080 (#0) * Trying 12.34.567.890... connected * Connected to myserver (12.34.567.890) port 8080 (#0) > DELETE /rest/repository/atg/userprofiling/ProfileAdapterRepository/user/130037 H TTP/1.1 > User-Agent: curl/7.21.1 (i386-pc-win32) libcurl/7.21.1 zlib/1.2.5 > Host: myserver:8080 > Accept: */* > Cookie: DYN_USER_ID=140003; JSESSIONID=E8FF855FEF5C59ECF6FA9D1A69F1C30D; DYN_USE R_CONFIRM=1231cf3e7573bf936dbd29dbbbfe150b > < HTTP/1.1 410 Gone < Server: Apache-Coyote/1.1 < X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
168
< X-ATGVersion: version=QVRHUGxhdGZvcm0vMTAuMCxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjAgWyBQb GF0Zm9 ybUxpY2Vuc2UvMCBCMkNMaWNlbnNlLzAgIF0= < Content-Type: application/xml;charset=UTF-8 < Transfer-Encoding: chunked < Date: Mon, 01 Nov 2010 20:21:19 GMT < <?xml version="1.0" encoding="UTF-8"?> <atgResponse>true</atgResponse> * Connection #0 to host myserver left intact * Closing connection #0
169
170
14 Property Filtering
The ATG platform REST Web Services include functionality that filters properties from output. Use this functionality to: Mark a property in a Nucleus component or repository item as hidden or not writable. Configure the system to override the default functionality of outputting all items and instead output only the items defined in the filtering configuration file. Add your own custom properties for components or repository items and specify the sources of their values.
An extension of the property filtering feature, called property aliasing, allows you to create virtual components with properties that assemble values from a variety of sources.
Default Filtering
The filtering configuration file is located at /atg/rest/filtering/filteringConfiguration.xml in your ATG platform servers configuration path. To customize it, create that file in your own module and the servers XML combination functionality will combine all the filteringConfiguration.xml files. 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"/>
171
14 - Property Filtering

</component> </rest-filtering>
</item-descriptor>
The default-include attribute tells the server that it should return only the values specified inside this component tag and ignore all other properties of the Nucleus component or repository item. The following sample adds additional properties which do not exist in the Nucleus component or repository item. The sample also configures where the values for these virtual properties come from. The property called virtual1 does not exist in the /some/Component bean. Its value, specified by the target attribute, is the value of property2 in the same object. Similarly, the repVirtual1 property returns the value of repProperty2 as its value. The target attribute also allows for subproperties to be specified, as the sample demonstrates for the virtual2 and repVirtual2 properties. Note that the dot notation can be more than one level deep.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> </item-descriptor> </component> </rest-filtering>
The next sample extends the previous one by adding a component attribute to the property tag and using that in combination with the target tag. This demonstrates how the value of a property can come from another Nucleus component. (Note that the component attribute can only reference a Nucleus component.) Dot notation can be used in the target attribute when the component attribute is used.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/>
172
<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 propertycustomizer attribute, as shown in the following sample.
<rest-filtering> <component name="/some/Component" default-include="true"> <property name="property1" hidden="true"/> <property name="property2" writable="false"/> <property name="virtual1" target="property2"/> <property name="virtual2" target="property2.subproperty"/> <property name="virtual3" component="/some/other/Component" target="aProperty"/> <property name="virtual4" property-customizer="some.class.Here"/> </component> <component name="/some/Repository" default-include="true"> <item-descriptor name="anItemDescriptorName"> <property name="repProperty1" hidden="true"/> <property name="repProperty2" writable="false"/> <property name="repVirtual1" target="repProperty2"/> <property name="repVirtual2" target="repProperty2.subproperty"/> <property name="repVirtual3" component="/some/other/Component" target="aProperty" /> <property name="repVirtual4" property-customizer="some.class.Here"/> </item-descriptor> </component> </rest-filtering>
When using the property-customizer attribute, the value should be the name of a class which implements the atg.rest.filtering.RestPropertyCustomizer interface, shown below.
public Object getPropertyValue(String pPropertyName, Object pResource); public void setPropertyValue(String pPropertyName, Object pValue, Object pResource );
173
Specifying the Filter Depth

You can control the nested level at which a filter will be applied. The number of nested levels at which the filter is applied is the filter depth. A filter depth of zero indicates that the filter should apply only to the immediate properties of the component the filter is configured for. A filter depth of one indicates that the filter should apply to the first nested level of properties. To set the filter depth for a repository, add the depth attribute to the item-descriptor element. For example:
<component name="/atg/userprofiling/ProfileAdapterRepository" default-include="false"> <item-descriptor name="user" depth="1"> <property name="wishlist" hidden="false"/> <property name="creditCards" hidden="false"/> </item-descriptor> </component>
To set the filter depth for a non-repository component, add the depth attribute to the component element. For example:
<component name="/atg/resttest/BeanTest" depth="0" default-include="false"> <property name="repository" hidden="false"/> </component>
Filtering for One Request

Use the atg-rest-property-filters control parameter to apply property filtering to individual REST Web Services requests. The value of the control parameter uses the same format as the rest-filtering element in the /atg/rest/filtering/filteringConfiguration.xml configuration file. See Default Filtering. Use JSON markup for the atg-rest-property-filters value. The components of the JSON value are shown below.
{ "<componentName>": [ { "item-descriptor": "<itemDescriptorName>", "depth": <depthInt>, "properties":
174
{ "<propertyName>": { "hidden": <boolean>, "writable": <boolean>, "target": "<target-dot-notation>", "component": "<component-path>", "property-customizer": "<customizer-class-name>" }, ... }, ... }, ... ], ... }
For example, the following atg-rest-property-filters control parameter value specifies that only the wishlist property will be returned for user repository items. It also specifies that only the eventType and published values will be returned for the wishlist property.
{ "/atg/userprofiling/ProfileAdapterRepository": [ { "item-descriptor": "user", "depth": 0, "properties": { "wishlist": { } } } ], "/atg/commerce/gifts/Giftlists": [ { "item-descriptor": "gift-list", "depth": 1, "properties": { "eventType": { }, "published": { } } } ] }
175

Property Aliasing
Property aliasing allows you to create virtual components with properties that assemble values from a variety of sources. Use virtual components to gather data from a variety of sources and return it in a single REST Web Services request. To create a virtual component with property aliasing: 1. Add a component element to the
/atg/rest/filtering/filteringConfiguration.xml configuration file for your ATG platform server. Specify the Nucleus path for the virtual component in the name attribute of that element.
2.
Include one or more property elements in the component element. Either draw the value of the component from another component property using the component and target attributes or from a custom class using the property-customizer attribute.
The following sample creates a virtual component. It specifies the name of a component that does not exist in the name attribute of the component tag, thus creating a virtual component. When creating virtual components in this way, do not use the item-descriptor tag. When this component is requested, the list of properties which is specified inside the component tag will be rendered. When requesting this component, use only the property tag with the component/target attributes or the property-customizer attribute, as the others do not provide value.
<rest-filtering> <component name="/some/nonexisting/Component"> <property name="property1" component="/some/other/Component" target="aProperty"/> <property name="property2" property-customizer="some.class.Here"/> </component> <rest-filtering>
176
15 Configuring the REST Server
Configure the ATG platform REST Web Services by setting the parameters described in the following sections.
/atg/rest/Configuration
This section explains configuration properties that are set on the /atg/rest/Configuration component.
defaultOutputCustomizer
This configuration property controls the markup that the REST Web Services server uses for returned data. See Choosing Output Markup. The following example specifies that the server should use XML format for the data it returns.
defaultOutputCustomizer=/atg/rest/output/XMLOutputCustomizer
maxDepthAllowed
This configuration property controls the maximum number of nested property levels that you can expand in returned data. See Expanding Multiple Values and Complex Objects. The following example specifies that only three nested levels may be expanded.
maxDepthAllowed=3
/atg/rest/processor/BeanProcessor
This section explains configuration properties that are set on the /atg/rest/processor/BeanProcessor component.
returnFormHandlerExceptionsByDefault
This configuration property controls whether the REST Web Services server will return information about the exceptions it encounters while invoking form handlers. See Returning Form Handler Exceptions. The
177
15 - Configuring the REST Server
following example specifies that exceptions should be included in the HTTP response to a Web Services request.
returnFormHandlerExceptionsByDefault=true
returnFormHandlerPropertiesByDefault
This configuration property controls whether the REST Web Services server will return the properties of the form handler components it invokes. See Returning Form Handler Properties. The following example specifies that the form handler properties should be included in the HTTP response to a Web Services request.
returnFormHandlerPropertiesByDefault=true
/atg/rest/output/JSONOutputCustomizer
This section explains configuration properties that are set on the /atg/rest/output/JSONOutputCustomizer component.
showRestPaths JSON
This configuration property specifies whether the REST Web Services server will return complex property values as Nucleus paths or by including the actual complex data in an HTTP response. See Expanding Multiple Values and Complex Objects. Setting the showRestPaths property on the /atg/rest/output/JSONOutputCustomizer component only affects returned data that is formatted using JSON markup. The following example specifies that multiple values and complex objects should be expanded in returned data.
showRestPaths=false
/atg/rest/output/XMLOutputCustomizer
This section provides information about configuration properties that may be set on the /atg/rest/output/XMLOutputCustomizer component.
showRestPaths XML
This configuration property specifies whether the REST Web Services server will return complex property values as Nucleus paths or by including the actual complex data in an HTTP response. See Expanding Multiple Values and Complex Objects.
178
Setting the showRestPaths property on the /atg/rest/output/XMLOutputCustomizer component only affects returned data that is formatted using XML. The following example specifies that multiple values and complex objects should be expanded in returned data.
showRestPaths=false
/atg/rest/processor/RepositoryProcessor
This section explains configuration properties that are set on the /atg/rest/processor/RepositoryProcessor component.
acceptJSONInput
This configuration property specifies whether the REST Web Services server will accept standard JSON markup for setting collection or map values on repository item properties. See JSON Markup Input for Multiple Value Repository Item Properties. The following example specifies that the REST Web Services server will accept JSON markup for setting multiple value repository item properties.
acceptJSONInput=true
appendMultiValuesByDefault
This configuration property specifies whether the values you set in repository item properties should be added to an existing set of values or should replace them. This only applies to repository item properties that accept multiple values. See Multiple Values in Input. The following example specifies that values set in a repository item property that holds multiple values should be added to the existing list. The existing values will remain set.
appendMultiValuesByDefault=true
/atg/rest/processor/RestSecurityProcessor
This section explains configuration properties that are set on the /atg/rest/processor/RestSecurityProcessor component.
allowAccessForUnsecuredRepository
This configuration property specifies whether the REST Web Services server will allow clients to get or set properties in unsecured repositories. Allowing this access is not recommended in a production
179
environment. Configure repository security before allowing REST Web Services clients to interact with repositories. See Repository Security. The following example specifies that any REST Web Services client may get or set properties in unsecured repositories. Use this setting for testing only.
allowAccessForUnsecuredRepository=true
180
16 Security for REST Web Services
This section provides information about the way the ATG platform REST Web Services server secures its interface and how it interacts with the underlying security system for the ATG platform in general.
Security Overview
The ATG platform REST Web Services server uses the underlying security system of the ATG platform. HTTP clients that invoke REST Web Services functionality behave in a manner that is similar to human users logging into an ATG platform user interface and interacting with its functionality. To understand the security system used by the REST Web Services server you must understand the system used by the ATG platform. See Managing Access Control in the ATG Programming Guide.
Logging In and Session IDs

The REST Web Services server will only process requests if the HTTP client sending them has an active HTTP session. Clients must log in to the server before performing operations. The server will provide a session ID which the client must present with each REST Web Services request. See Logging In.
Nucleus Component Granularity

The security functionality for ATG platform REST Web Services allows security to be placed on multiple levels of granularity for Nucleus components. The default configuration for ATG platform REST Web Services is to not allow access to any components. This means that you will need to configure security to be able to call methods or access properties on Nucleus components. Security on Nucleus components can be configured globally for all components, at the component level for all properties and methods, at the property level, at the method level, and for entire Nucleus sub-trees. The REST security subsystem depends on the ATG security system and therefore uses ACLs which are similar to those used to configure security in other parts of an ATG server. The personas can be users, organizations, or roles. The valid rights which can be assigned to a persona are read, write, and execute. Read and write refer to Nucleus properties and execute refers to Nucleus methods. To configure multiple personas, use a semicolon (;) character to separate each access control entry (persona/rights).
181
16 - Security for REST Web Services
The REST security configuration file is located at

/atg/rest/security/restSecurityConfiguration.xml. To add your own security configuration
create a file at that location in the config directory of your module. Note: The ATG platform REST Web Services module does not provide functionality for securing repository items All ATG repository security is handled by the ATG secured repository system, which works in conjunction with the ATG Security System to provide fine-grained access control to repository item descriptors, individual repository items, and even individual properties. For more information, see the ATG Repository Guide.
Quick Setup for Testing

Once the server is running with the REST module, your platform is now able to accept and process REST requests. Before you begin coding, you must configure the Web Services security component. By default: The security components in the ATG platform REST Web Services require you to be logged into the server in order to make calls. No users have access to any components, so even a logged-in user will not be able to successfully make any REST requests.
In a development environment, you can set a default ACL in the security configuration file. This allows all the specified users to have access to all Nucleus components. Important: This functionality is provided for convenience and should not be used in a production environment unless that is the specified intent. To set a default ACL in the security configuration layer, create a file in your localconfig directory at atg/rest/security named restSecurityConfiguration.xml. Add the following lines to the file, replacing #username# with the name of a valid profile for logging onto your ATG system.
<programlisting> <rest-security> <default-acl value="Profile$login$#username#:read,write,execute"/> </rest-security> </programlisting>
Global Security
To configure global security, use the default-acl tag. This tag defines which personas have access to Nucleus components. In the following example, all users who are assigned the restUser role have read and write access to all Nucleus properties and execute access for all methods on Nucleus components. The default-acl tag is optional. This example assumes that a role called restUser has already been created in the profile repository.
182
<rest-security> <default-acl value="Profile$role$restUser:read,write,execute"/> </rest-security>
Component Security
To configure security on a specific component, use the resource tag. This tag, along with the component attribute, allows you to define which users have access to the specified component. You could disable security entirely for the specified component by using the optional secure attribute. In the following example, the /some/Component component is configured so that only the user whose login is restAdmin has full access to it; users with the restUser role only have read access. In addition, the /some/other/Component component is configured to disable security. This means that all users have full access to all properties and methods of that component.
<rest-security> <default-acl value="Profile$role$restUser:read,write,execute"/> <resource component="/some/Component"> <default-acl value="Profile$login$restAdmin:read,write,execute;Profile$role$restUser:read"/> </resource> <resource component="/some/other/Component" secure="false"/> </rest-security>
Property and Method Security

To configure security on a component property or method, add a property or method tag within the resource tag. The property and method tags allow you to control which users have access to specific properties and methods. In the following example, property1 and methodA in /some/Component can be accessed only by the restAdmin user. property2 and methodB can be accessed by anyone, because security has been disabled on it.
<rest-security> <default-acl>Profile$role$restUser:read,write,execute"</default-acl> <resource component="/some/Component"> <default-
183

> </property>
acl value="Profile$login$restAdmin:read,write,execute;Profile$role$restUser:read"/
<property name="property1"> <acl value="Profile$login$restAdmin:read,write"/>
<property name="property2" secure="false"/> <method name="methodA"> <acl value="Profile$login$restAdmin:execute"/> </property> <method name="methodB" secure="false"/> </resource> <resource component="/some/other/Component" secure="false"/> </rest-security>
Methods which are overloaded and have different security requirements require a signature attribute, available on the method tag. This attribute allows for a Java method signature that uniquely identifies the method.
Repository Security
The ATG platform REST Web Services module does not provide functionality for securing repository items All ATG repository security is handled by the ATG secured repository system, which works in conjunction with the ATG Security System to provide fine-grained access control to repository item descriptors, individual repository items, and even individual properties. For more information, refer to the ATG Repository Guide
Securing Groups of Components

The ATG platform REST Web Services provide the ability to secure groups of components within the same Nucleus sub-tree. This is accomplished by using the * wildcard character. Note that * is the only wildcard character allowed. The following example sets the ACL for all components within the /atg/commerce sub tree to be accessible only by users with the restCommerceUser role.
<rest-security> <default-acl>Profile$role$restUser:read,write,execute"</default-acl>
184
<resource component="/atg/commerce/*"> <default-acl value="Profile$role$restCommerceUser:read,write,execute"/> </resource> </rest-security>
185
186
17 ATG Client Libraries
The ATG platform REST Web Services package includes two client libraries: Java Client Library ActionScript Client Library
These libraries make ATG platform REST Web Services easier to use by hiding the complexity of creating connections, assembling payloads for requests, and processing responses.
Java Client Library

The Java client library provides a number of classes that assist in making REST calls to the ATG platform REST Web Services. The following classes are the ones youll use most often:
RestSession
Handles login and logout, manages connections, and issues requests.

RestResult
Accesses the RestResult object that is returned when a request is made to the server. This class also includes convenience methods for retrieving the response data.
RestComponentHelper
Contains a series of static helper methods that simplify issuing Nucleus component calls to the server.
RestRepositoryHelper
Contains a series of static helper methods that simplify issuing repository calls to the server.
Creating Requests
You will find it easiest to make most ATG platform 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.
187
17 - ATG Client Libraries
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.
public static RestResult getComponent(String pComponentPath, Map<St ring,Object> pParams, RestSession pSession)
Returns all the properties of the specified Nucleus component.

public static RestResult getPropertyValue(String pComponentPath, St ring pProperty, Map<String,Object> pParams, RestSession pSession)
Returns the requested property from the specified Nucleus component.

public static RestResult setPropertyValue(String pComponentPath, St ring pProperty, Object pValue, Map<String,Object> pParams, RestSess ion pSession)
Sets a value on the specified Nucleus component property.

public static RestResult executeMethod(String pComponentPath, Strin g pMethodName, Object[] pArguments, Map<String,Object> pParams, Res tSession pSession)
Calls a public method on the specified Nucleus component. The Object[] pArguments parameter is an array of method arguments. This parameter should contain one Object for each of the method parameters. For example, if the method takes an int, then a java.lang.Integer object should be passed. The Java client library handles converting the object for transport to the server and the ATG REST module handles converting it to an int. If any parameter object is passed as a String, the parameter will be transported to the server without any changes. This means that a method that takes an int can have a java.lang.String object with a value of 2, for example, passed. For parameters that are complex objects, the object can be passed as a parameter and the library will attempt to convert it for transport. When the request is sent to the server, a new instance will be constructed and its properties populated with the values from the original object. Collections and Maps can also be transported. For more information, see Calling Methods with the Java Client Library.
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.
public static RestResult createItem(String pRepositoryPath, String pItemDescriptorName, Map<String,Object> pParams, RestSession pSessi on)
Returns the ID of the newly created repository item.
188
public static RestResult createItem(String pRepositoryPath, String pItemDescriptorName, String pItemId, Map<String,Object> pParams, Re stSession pSession)
Returns the ID of the newly created repository item.

public static RestResult removeItem(String pRepositoryPath, String pItemDescriptorName, String pItemId, Map<String,Object> pParams, Re stSession pSession)
Returns true if the repository item was successfully removed; otherwise, returns false.
public static RestResult getItem(String pRepositoryPath, String pIt emDescriptorName, String pItemId, Map<String,Object> pParams, RestS ession pSession)
Returns the contents of the repository item. If any of the properties are references to other items, Collections, arrays, or Maps, returns a REST URL that you can use to access the contents of the specific property. You can create a raw REST request to access the data for the property. For more information, see Creating a Raw REST Request.
public static RestResult getItems(String pRepositoryPath, String pI temDescriptorName, 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, St ring 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 REST Web Services. Make sure that all constants are explicitly included in the RQL statements. See information about parameters in RQL queries in the ATG Repository Guide.
public static RestResult getPropertyValue(String pRepositoryPath, S tring pItemDescriptorName, String pItemId, String pProperty, Map<St ring,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, S tring pItemDescriptorName, String pItemId, String pProperty, Object pValue, Map<String,Object> pParams, RestSession pSession)
189
Creating a RestSession Object

The ATG platform REST Web Services calls are executed within the context of an HTTP session. This enables a client application to maintain state across requests and to use login information for security purposes. The RestSession class contains all the logic required for connecting and communicating with an ATG server. The following code creates a new RestSession object:
RestSession session = RestSession.createSession(host, port, username, password);
Note: You can perform multiple REST Web Services requests during an HTTP session. See information about HTTP sessions and the REST Web Services server in Logging In.
RestSession class properties

The RestSession class includes the following properties. Some are set when the object is created and others can be changed after the object has been constructed:
Property
Hostname
Description The name of the host which the session will or is connected to. Default is localhost. The port number which the session will use. Default is 80. The username the session will use to connect. The password the session will use to connect. The scheme the session will use to connect. Default is HTTP expect for login calls. The web application context root for ATG platform REST Web Services. Default is /rest. 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. Tells the session object to use the HTTPS scheme for login calls. Default is true. The HTTPS port number which the session will use. Default is 443. The userId of the connected user. This value is set after logging in.
Port Username Password Scheme
restContextRoot
useInternalProfileF orLogin
useHttpsForLogin
httpsPort userId
190
sessionId Encoding inputFormat
The session ID of the current session. This value is set after logging in. The encoding to use when encoding parameter values. Default is UTF The default input format that is set on the server. Changing this value has no effect on the server. The default output format that is set on the server. Changing this value has no effect on the server
outputFormat
Logging in and Logging Out with the Java Client Library

The following code sample is a shell of a simple application. It does nothing more than login and logout. The most interesting portion of the following code sample is the execute method. Note: You can perform multiple REST Web Services requests during an HTTP session. See information about HTTP sessions and the REST Web Services server in Logging In. The sample first creates a RestSession object. It does this by calling the static
RestSession.createSession() method. The parameters to createSession are the hostname, port,
username, and password. By default all login calls are issued with HTTPS. If you do not want this functionality, set the value of the useHttpsForLogin flag to false on the session object, as the following sample does. The next section of code calls the login() method on the RestSession object. If the login attempt fails, then a RestClientException is thrown. The last section of code calls the logout() method and concludes the session.
import atg.rest.client.RestClientException; import atg.rest.client.RestComponentHelper; import atg.rest.client.RestResult; import atg.rest.client.RestSession; import java.io.IOException; public class RestClientSample { private String mUsername = null; private String mPassword = null; private String mHost = "localhost"; private int mPort = 80; private RestSession mSession = null; public RestClientSample() {} protected void parseArguments(String[] pArgs) throws Exception { for (int i = 0; i < pArgs.length; i++) { String arg = pArgs[i]; if (arg.equals("-user")) mUsername = pArgs[i+1];
191
else if (arg.equals("-password")) mPassword = pArgs[i+1]; else if (arg.equals("-host")) mHost = pArgs[i+1]; else if (arg.equals("-port")) mPort = Integer.parseInt(pArgs[i+1]);
if (isBlank(mUsername)) throw new Exception("Must supply username"); if (isBlank(mPassword)) throw new Exception("Must supply password"); } protected boolean isBlank(String pStr) { return (pStr == null || pStr.length() == 0 || pStr.trim().length() == 0); } protected void println(String s) { System.out.println(s); } protected void println(Throwable t) { t.printStackTrace(System.out); } protected void execute() throws RestClientException { mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword); mSession.setUseHttpsForLogin(false); try { String loginStatus = mSession.login(); if(loginStatus == null || "null".equals(loginStatus)) { mSession = null; System.out.println("Login Failed"); } else { System.out.println("Login Successful"); } } catch (Throwable t) { println(t); } finally { try { if(mSession != null) { mSession.logout(); System.out.println("Logout Successful");
192
} } 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); } } }
Accessing Data from the Server

Now you can build on the previous example by accessing a Nucleus component property. The example that follows makes a request for all the properties of a Nucleus component using the RestComponentHelper class. This class has several static convenience methods which assist in creating the requests and issuing them to the server. The getComponent() method take the path to a Nucleus component, a map of optional parameters, and the RestSession object and returns a RestResult object. The RestResult object can be used to access the data from the response. The following sample calls readInputStream() to return a String of the response data. In this case, you can assume that the server is using the default output format which is JSON. The string in response data will contain the JSON output. A JSON object is then constructed and output. Another alternative is to simply output responseData, but this sample illustrates how you might use the output. Similarly, if the output format was XML, you could create an XML document object using dom4j. The finally block includes a call to close the result. Doing this will release the underlying connection resources. If this call is omitted, the next call to the server using the same RestSession object will close the result.
protected void execute() throws RestClientException { RestResult result = null;
193

try { mSession.login();
mSession = RestSession.createSession(mHost, mPort, mUsername, mPassword); mSession.setUseHttpsForLogin(false);
println("Login Successful"); result = RestComponentHelper.getComponent("/atg/dynamo/Configuration", null, mSession); String responseData = result.readInputStream(); if (responseData != null) { JSONObject json = new JSONObject(responseData); println(json.toString()); } } catch (Throwable t) { println(t); } finally { if (result != null) result.close(); try { mSession.logout(); println("Logout Successful"); } catch (RestClientException e) { println(e); } } }
Creating a Raw REST Request

The RestComponentHelper and RestRepositoryHelper classes might not support every type of request you want to issue to the server. If this is the case, you can issue a request using the createHttpRequest() method of the RestSession class. There are two versions of this method:
public RestResult createHttpRequest(String pURL, Map<String,Object> pParam s, String pMethodType) public RestResult createHttpRequest(String pURL, Map<String,Object> pParam s, Object[] pArguments, String pMethodType)
The following table describes the arguments for each version of this method.
194
Argument
pURL
Description The URL to request, formatted as http://hostname:port/uri The pURL argument must be an absolute URL, including the hostname (and port, if it is not 80). The RestSession class includes a convenience method called getHostString() which returns a string containing the scheme, host, and port number. The caller can then append the remainder of the URL and pass the resulting string as the first argument to this method.
pParams
A Map of parameters to submit along with the request. This argument is the same as it would have been if you made the request using either of the helper classes. It contains parameters which can control certain aspects of the request.
pArguments
An array of Objects which contain the method parameter values. Use this argument only for method calls. The value is the same as it would be if calling the executeMethod() method on the RestComponentHelper class.
pMethodType
The HTTP method for the request: GET, POST, PUT, or DELETE. The atg.rest.client.RestConstants class contains constant values for these strings. In short, GET should be used when retrieving data, POST should be used when calling methods, PUT should be used when setting properties, and DELETE is used for deleting repository items. DELETE is not used when interacting with Nucleus components.
Handling Results
createHttpRequest() and all the helper class methods return a RestResult object that allows access
to various parts of the response. The most interesting and useful method on the RestResult is readInputStream(). This is a convenience method which will return the response data into a String
public String readInputStream() throws IOException
After calling this method the String object which is returned will contain the JSON or XML with the content which was requested. The REST module uses the org.json.jar library and the dom4j XML library internally. You can also use these libraries, or comparable libraries, in your applications. If the response data is large, you can access the input stream directly by calling getInputStream() on the RestResult. Other useful methods on the RestResult object are getResponseCode() and
getResponseMessage(). These return the responses response code and message, respectively. For
more information, see HTTP Status Codes.
195
The Java client library uses the java.net.HttpURLConnection class to communicate with servers. To access any functionality that the RestResult does not expose, call the getConnection() method to return the underlying HttpURLConnection object. When you are finished with the RestResult object, it is good practice to call the close() method. This releases any resources that the HttpURLConnection might hold. If the connection is not closed, the next request to the server will close the HttpURLConnection.
Accessing Components with the Java Client Library

This section explains how to work with components using the Java client library for the ATG platform REST Web Services.
Getting Component Data

The getComponent() method of the RestComponentHelper class returns a data stream that contains a representation of a component. The following code sample returns the Configuration component:
RestResult result = RestComponentHelper.getComponent("/atg/dynamo/Configuration", null, mSession)
Getting and Setting Property Values

The getPropertyValue() method of the RestComponentHelper class returns a data stream that contains the value of the specified property. The following code sample gets the value of the property httpPort from the Configuration component.
RestResult result = RestComponentHelper.getPropertyValue("/atg/dynamo/Configuratio n", "httpPort", params, session)
Use the RestComponentHelper.setPropertyValue() method to set property values on Nucleus components. The following code sample sets the value of the Configuration component property httpPort to 8580.
RestResult result = RestComponentHelper.setPropertyValue("/atg/dynamo/Configuratio n", "httpPort", "8580", params, session)
196
Calling Methods with the Java Client Library

You can use the ATG platform REST Web Services to call public methods on Nucleus components. If a method is overloaded, then the server will attempt to determine which method to call by looking at the number of arguments supplied. It is also possible to supply a method signature as a parameter to the RestComponentHelper.executeMethod() method. Supplying the atg-rest-method parameter allows you to specify the exact method to be called. The value of the parameter should be the Java method signature of the method to call. You can find the method signature for a method by using the javap command, which disassembles a class file. (The javap command is part of the JDK.) Depending on the return type of the method, the output will vary. If the output is an object, then it will return a JSON or XML stream which contains the values of all the properties in the object. If it is a simple type like an int or a String, it will return the value. The identifier for the return type is atgResponse.
Passing Parameters to Methods

If you use the Java or ActionScript client libraries that ship with the ATG platform REST Web Services, passing parameters to methods is as simple as supplying the Objects in the pArguments argument for the RestComponentHelper.executeMethod() method. For more information, see ATG Client Libraries. If one of the parameters is a simple type, then it should be wrapped in an object. For example, an int will become a java.lang.Integer, a boolean becomes a java.lang.Boolean, and so on. When you pass collections, Maps, and arrays as parameters, the client library attempts to convert those types. Date, Time, and Timestamp objects can also be passed, as shown in the following sample.
RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod" , new Object[] {1,2,3,4.4,5.5,true,'a',0xa}, null, session)
In order to pass repository items, use a preformatted string that takes the format of
repository Nucleus path:item descriptor name:item id
For example:
/atg/commerce/catalog/ProductCatalog:product:prod12345
When you reference a repository item this way, the server performs a lookup and uses the item as the method argument. For example:
RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod", new Object[] {"/atg/commerce/catalog/ProductCatalog:product:prod12345"} , null, session)
If a method takes a GenericService as an argument, simply passing the Nucleus path as a string will cause the server to lookup the Nucleus component and use it as the method argument. For example:
197
RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod", new Object[] {"/atg/dynamo/Configuration"}, null, session)
If passing a complex Java object, attempt to add the object to the pArguments argument and call the method. In most cases, the argument will not need to be transformed before it is transported to the server. The client library will make an attempt at converting the object for you.
MyObject myObject = new MyObject(); RestResult result = RestComponentHelper.executeMethod("/some/Component", "aMethod", new Object[] {myObject}, null, session)
Calling Handler Methods

Form handlers use special handler methods for linking form elements with Nucleus components. One of the more powerful features in the ATG platform REST Web Services module is the ability to call handler methods. If you have existing JSP-based applications, all the functionality which has previously been exposed in those applications can be reused with REST based applications. Use RestComponentHelper.executeMethod() to call handler methods. Keep the following in mind when calling a handler method The method name, the second argument in the executeMethod() method, should not contain the handle prefix. For example, to call the handleCreate method, it should be specified simply as create in the pMethodName argument. The pArguments parameter should always be null when you call a handler method.
The following code sample calls the handleCreate method on a specified form handler:
RestResult result = RestComponentHelper.executeMethod("/some/FormHandler", "create", null, null, session)
As long as a form handler does not submit a redirect, the execution would be similar to a regular method call. For those form handler methods which do redirect, the redirect will be intercepted and returned back to the client as an exception.
Passing Parameters to Form Handlers

Form handler parameters which need to be supplied should be added to the params argument. In a JSP page these parameters would be the input tags in a JSP form. The following example calls the handleCreate() method on a form handler. The inputs to the form handler are a first and last name.
Map<String,String> params = new HashMap<String,String>(); params.put("firstName", "Andy"); params.put("lastName", "Jones");
198
RestResult result = RestComponentHelper.executeMethod("/some/FormHandler", "create", null, params, session);
Accessing Repository Items with the Java Client Library

The ATG platform REST Web Services RestRepositoryHelper class exposes methods that perform basic Repository operations.
Getting Repository Items with the Java Client Library

The getItem() method of the RestRepositoryHelper class returns a data stream that contains all the property values of a repository item. The following code sample returns an array of URLs. Issuing a request using the
RestSession.createHttpRequest() method returns the property values of the requested item.
RestResult result = RestRepositoryHelper.getItem("/atg/commerce/catalog/ProductCat alog", "product", productId, params, session)
The getItems() method retrieves multiple repository items of the same type in a single call. The following code sample returns an array of URLs:
RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCa talog", "product", params, session)
When a getItems() call returns many items, you can control the number of items returned with the atg-rest-index and atg-rest-count parameters. The atg-rest-index parameter tells the server which item to return first. The atg-rest-count parameter tells the server how many items past the index item to return. In the following code sample, the first query, with an index of 0 and a count of 10, retrieves 10 items at a time. The next query has an index of 10 and a count of 10, third, index of 20 and count of 10, and so on.
Map<String,String> params = new HashMap<String,String>(); params.put(RestConstants.COUNT, 10); params.put(RestConstants.INDEX, 0); RestResult result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCa talog", "product", params, session); params.put(RestConstants.INDEX, 10); result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog",
199
"product", params, session); params.put(RestConstants.INDEX, 20); result = RestRepositoryHelper.getItems("/atg/commerce/catalog/ProductCatalog", "product", params, session);
Repository IDs
Each repository item has a unique identifier, called a repository ID. Depending on the repositorys configuration, the repository ID might not be exposed as a property of the repository item. However, when a repository item is returned with a Rest RepositoryHelper method, you can reliably retrieve its repositoryID by getting the value of the repositoryId property.
Adding Repository Items

Create a repository item by calling the RestRepositoryHelper.createItem() method. You can supply a repository ID for the newly created item or you can allow the server to generate a repository ID for you. A createItem() call returns a data stream that contains all the properties of the created item. This is the same data stream that is returned when you call RestRepositoryHelper.getItem(). The following code sample adds a repository item and allows the server to generate the repository ID:
RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/Product Catalog", "product", params, session);
The following code sample adds a repository item and specifies the value of myProductId-12345 as the repository ID:
RestResult result = RestRepositoryHelper.createItem("/atg/commerce/catalog/Product Catalog", "product", "myProductId-12345", params, session);
Deleting Repository Items

Remove a repository item by calling the RestRepositoryHelper.removeItem() method. A removeItem() call returns a data stream that contains the string true if the item was removed. If the item was not removed, the call throws an exception. The following sample removes a repository item:
RestResult result = RestRepositoryHelper.removeItem("/atg/commerce/catalog/Product Catalog", "product", "myProductId-12345", params, session);
200
Getting Repository Item Properties with the Java Client

The getPropertyValue() method of the RestRepositoryHelper class returns a data stream that contains the value of the specified property. The following sample gets the property value displayName from the product repository item.
RestResult result = RestRepositoryHelper.getPropertyValue("/atg/commerce/catalog/P roductCatalog", "product", "prod12345", "displayName", params, session);
Setting Repository Item Properties with the Java Client

The setPropertyValue() method of the RestRepositoryHelper class sets the value of the specified property. The following sample sets the property displayName to the string My Modified Display Name.
RestResult result = RestRepositoryHelper.setPropertyValue("/atg/commerce/catalog/P roductCatalog", "product", "prod12345", "displayName", "My Modified Display Name", params, session);
Performing Queries for Repository Items

Performing queries for repository items using RQL is similar to retrieving them with getItems(), but querying provides for more control over the items included in the results. Use the RestRepositoryHelper.executeRQLQuery() method to execute and RQL query. To request a range of items, use the atg-rest-index and atg-rest-count parameters with the executeRQLQuery() method, just as youd use them with getItems(). See Getting Repository Items for more information. In the following example, the INDEX and COUNT keywords in the RQL language are used instead of the atg-rest-index and atg-rest-count parameters.
Map<String,String> params = new HashMap<String,String>(); params.put(RestConstants.COUNT, 10); params.put(RestConstants.INDEX, 0); RestResult result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/Pr oductCatalog", "product", "age >= 30", params, session); params.put(RestConstants.INDEX, 10); result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalo g", "product", "age >= 30", params, session);
201

g",
params.put(RestConstants.INDEX, 20); result = RestRepositoryHelper.executeRQLQuery("/atg/commerce/catalog/ProductCatalo "product", "age >= 30", params, session);
ActionScript Client Library

ActionScript is the programming language for the Adobe Flash Player run-time environment. This library is useful for client applications written in Adobe Flash or Adobe Flex. Note: The ATG platform REST Web Services were tested with ActionScript 3. The ActionScript client library is nearly identical in structure to the Java client library. The main difference between the two libraries is the way they handle results: The Java client library uses the RestResult class to handle results. The ActionScript library does not include a RestResult class; instead, it handles results using a callback mechanism. Therefore, helper class methods and the createHttpRequest() method for the ActionScript client library take a result handler and fault/error handler functions as arguments.
The following code sample illustrates how the ActionScript client library handles results.
public function getPropertyValue():void { RestComponentHelper.getPropertyValue("/atg/dynamo/Configuration", "httpPort", null, session, handleResult, handleFault); // get the httpPort property from the Configuration component } public function handleResult(pEvent:Event):void { var xml:XML = new XML(pEvent.target.data); // create an XML object populateGridWithXML(xml); // populate the control with the XML output } public function handleFault(pEvent:Event):void { Alert.show("Fault"); // display an error dialog }
atg.rest.client.RestComponentHelper
The RestComponentHelper class simplifies Nucleus requests.
202
The RestComponentHelper methods are written in ActionScript as follows. For details about individual class methods, refer to the Java client library section.
public static function getComponent(pComponentPath:String, pParams:Array, pSession :RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function getPropertyValue(pComponentPath:String, pProperty:String, p Params:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function setPropertyValue(pComponentPath:String, pProperty:String, p Value:Object, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function executeMethod(pComponentPath:String, pMethodName:String, pA rguments:Array, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void
atg.rest.client.RestRepositoryHelper
The RestRepositoryHelper class simplifies repository requests. The RestRepositoryHelper class methods are written in ActionScript as follows. For details about individual class methods, refer to the Java client library section.
public static function getItem(pRepositoryPath:String, pItemDescriptorName:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Func tion):void public static function getItems(pRepositoryPath:String, pItemDescriptorName:String , pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function executeRQLQuery(pRepositoryPath:String, pItemDescriptorName :String, pRQL:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Func tion):void public static function getPropertyValue(pRepositoryPath:String, pItemDescriptorNam e:String, pItemId:String, pProperty:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Func tion):void public static function setPropertyValue(pRepositoryPath:String, pItemDescriptorNam e:String, pItemId:String, pProperty:String, pValue:Object, pParams:Object, pSession:RestSession, pResultHandler:Function, pFa ultHandler:Function):void
203

tion):void
public static function createItem(pRepositoryPath:String, pItemDescriptorName:Stri ng, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Function):void public static function createItemWithId(pRepositoryPath:String, pItemDescriptorNam e:String, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Func
public static function removeItem(pRepositoryPath:String, pItemDescriptorName:Stri ng, pItemId:String, pParams:Object, pSession:RestSession, pResultHandler:Function, pFaultHandler:Func tion):void
Calling Methods with ActionScript

The ActionScript client librarys RestClientHelper class includes the following helper methods, which convert arrays, Lists, and Objects to MultiValue objects:
public static function convertArrayToMultivalue(pValue:Array, pMultiValueType:Stri ng, pComponentType:String, pFormat:String, pSession:RestSession):String public static function convertIListToMultivalue(pValue:IList, pMultiValueType:Stri ng, pComponentType:String, pFormat:String, pSession:RestSession):String public static function convertObjectToMultivalue(pValue:Object, pMultiValueType:St ring, pKeyType:String, pValueType:String, pFormat:String, pSession:RestSession):String
The following table describes the arguments for each of these methods.
Argument
pMultiValueType
Description The absolute path of a Java class, such as java.util.ArrayList. Be sure to specify a valid class name and not an interface name. The class type of the component to instantiate for each element in the multivalued type. For example, an array of integers in ActionScript could be converted to an ArrayList of java.lang.Integer objects. The servers input format type. This can be retrieved from the session objects inputFormat property.
pComponentType
pFormat
204
pKeyType pValueType
ActionScript objects act as associative arrays (similar to java Maps), the convertObjectToMultivalue() method takes a key type and value type. These arguments are similar to pComponentType and are absolute names of Java classes to use for the key and value objects in the Java Map.
Similar to the Java client library, passing arguments to methods is generally straightforward. For primitive types, just add them to the pArguments array.
var result:RestResult = RestComponentHelper.executeMethod("/some/Component", "aMet hod", [1,2,3,4.4,5.5,true,'a',0xa], null, session, handleResult, handleFault)
To pass a reference to a repository item, use the format

<repository path:item descriptor name:item id>
For example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", ["/atg/commerce/catalog/ProductCatalog:product:prod12345"], null, session, handleResult, handleFault)
To pass a reference to a Nucleus component, pass the Nucleus component path. For example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", ["/atg/dynamo/Configuration"], null, session, handleResult, handleFault)
The following example is a call to a method which takes a repository item array and a GenericService array.
<programlisting> var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", [["/atg/commerce/catalog/ProductCatalog:product:prod12345", "/atg/commerce/catalog/ProductCatalog:product:prod67890"], ["/atg/dynamo/Configuration","/atg/dynamo/Configuration"]], null, session, handleResult, handleFault)
As mentioned above, arrays, ILists, and Objects must be converted before being passed to the server. The following example demonstrate passing an array using the helper methods in the RestClientUtils class.
205

"aMethod",
var arrayCollection:ArrayCollection = new ArrayCollection(["abc","def"]); var result:RestResultRestComponentHelper.executeMethod("/some/Component", [RestClientUtils.convertIListToMultivalue(arrayCollection, "java.util.ArrayList", "java.lang.String", RestConstants.JSON, session)], null, session, handleResult, handleFault);
The following example, which calls executeMethod(), produces the same result as the previous example:
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", ["java.util.ArrayList:java.lang.String:[\"abc\",\"def\"]"], null, session, handleResult, handleFault)
The following examples use the helper methods in the RestClientUtils class.
var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod ", [RestClientUtils.convertArrayToMultivalue(["abc","def"], "java.util.HashSet", "java.lang.String", RestConstants.JSON, session)], null, session, handleResult, handleFault) var obj:Object = new Object(); obj["abc"] = 123; obj["def"] = 456; var result:RestResultRestComponentHelper.executeMethod("/some/Component", "aMethod", [RestClientUtils.convertObjectToMultivalue(obj, "java.util.HashMap", "java.lang.String", "java.lang.Integer", RestConstants.JSON, session)], null, session, handleResult, handleFault)
Formatting Input with ActionScript

The option to use JSON or XML with ActionScript is available. In order to use JSON you will need to include the Adobe corelib library. This library contains functionality to encode and decode JSON streams. In the example below, the pEvent object is of type Event and is supplied by the Flash runtime when the handler method is called. pEvent.target.data contains the response data stream. This stream is decoded into an Object. The sample iterates through the properties constructing an object for each name/value pair and then adds it to an ArrayCollection object.
var json:Object = JSON.decode(pEvent.target.data); for (var propName:String in json) arrayCollection.addItem({name: propName, value: json[propName]});
206
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()}); }
207
Index
.
.NET clients ATGWS.dll, 70 before calling Web Services, 67 calling Web Services, 65 client stubs, 66 security, 65 session sharing, 54, 66 transactions, 66 Web Service call examples, 69
A
about ATG Web Services, 53, 65 acceptJSONInput, 179 accessing ATG Web Services from .NET clients, 65 accessing ATG Web Services from Java clients, 53 ActionScript client library REST Web Services, 202 addItem operations, 92 add-item tag, 102 AddService, 48 data validation, 48 allowAccessForUnsecuredRepository, 179 appendMultiValuesByDefault, 179 arg1 functional parameter, 127 asynchronous requests, 137 ATG client libraries REST Web Services, 187
ATG Web Services, 10, 24 atg.adapter.integrations.ChangedPropertyBean, 88 atg.adapter.integrations.IntegrationRepository, 85 atg.adapter.integrations.IntegrationRepositoryItem, 88 atg.adapter.integrations.IntegrationRepositoryItemDescri ptor, 87 atg.adapter.integrations.IntegrationRepositoryView, 89 Atg.DotNet.WebService API, 70 Atg.DotNet.WebService.ComplexType, 74 Atg.DotNet.WebService.NoSuchPropertyException, 75 Atg.DotNet.WebService.Property, 73 Atg.DotNet.WebService.RepositoryItem, 72 Atg.DotNet.WebService.RepositoryItemRef, 74 Atg.DotNet.WebService.RepositoryItemSerializationExcep tion, 76 atg.integrations.BaseCommand, 109 atg.integrations.BaseCommandHandler, 109 atg.integrations.Command interface, 107 atg.integrations.CommandHandler interface, 108 atg.integrations.CommandResults, 109 atg.integrations.MapRPCDroplet, 110 atg.repository.databinding.MappingRepositoryItem, 88 atg.repository.RepositoryService, 34 atg.repository.xml.AddService, 48 atg.repository.xml.GetService, 46 atg.repository.xml.RemoveService, 51 atg.repository.xml.UpdateService, 49 atg.repository.xml.XMLSchemaManager, 44 atg-rest-form-tag-priorities, 158 atg-rest-output, 135 atg-rest-property-filters, 174 atg-rest-return-form-handler-exceptions, 157 atg-rest-return-form-handler-properties, 157 atg-rest-show-rest-paths, 138 atg-rest-transient, 166 atg-rest-user-input, 137 ATGWS.dll client stubs for .NET, 66, 70 deserializing RepositoryItems, 66 installing, 67 serializing RepositoryItems, 66 Axis calling Web Services using, 58
C
client stubs for .NET, 66 client stubs for Java clients. See static Web Service calls command operations addItem, 92
208
Index
executeQuery, 90 getItem, 91 Integration Repository, 90 removeItem, 93 updateItem, 91 CommandHandlers, 108 CommandResults, 109 commands, 108 executing, 108 executing in pages, 110 invoking, 108 component properties getting, 149 in REST Web Services, 149 setting, 150 components REST path for, 117 configuration of the REST Web Services server, 177 Content-Type, 129 control parameters, 125 CookieContainer, 54, 55, 66 .Net client example, 69 Java client example, 59, 60 curl command-line utility, 118 custom Web Services, 13
F
filter depth specifying default, 174 specifying for one request, 174 filteringConfiguration.xml, 171 form handlers form value priority, 158 invoking with the REST Web Services, 155 returning exceptions, 157 returning properties, 157 submitting form values, 156 form values priority, 158 functional parameters, 127 positional, 127
G
generateXMLSchema utility, 43 getItem operations, 91 get-item tag, 101 GetService, 46
H
HTTP status codes, 134 HTTP methods for REST Web Services, 119 HTTP requests, 116
D
data binding repository to XML. See repository to XML data binding data validation, 48, 49 default-acl, 182 defaultOutputCustomizer, 135, 177 definition files Integration Repository, 83, 98 derived properties updating, 92 derived-properties tag, 103 deserializing content on the client side, 61, 70 dot Net clients. See .NET clients DTDs Integration Repository, 103 repository to XML mapping files, 38 dynamic Web Service calls, 60 distinction from static calls, 58 limitations, 58 Dynamo Administration UI Web Service creation wizard, 15, 27 Web Service registry, 25 Web Service security manager, 24
I
input values REST Web Services, 131 Installing ATGWS.dll, 67 Integration Data repository, 94 cleaning up, 95 Integration Repository, 79 APIs, 84 architecture, 79 command operations, 90 definition files, 83, 98 DTD, 103 examples, 95 operations, 79 persistent cache, 94 queries, 89 setting up, 82 IntegrationRepository component, 83, 85 IntegrationRepositoryView, 79 internal users logging into REST Web Services server, 122
E
errors, 144 exceptions, 144 returning for form handlers, 157 executeQuery operations, 90 external users logging into REST Web Services server, 121
209
Index
item-descriptor tag, 99 itemRef attribute, 45
Nucleus component Web Services, 16 Nucleus components REST, 113
J
Java client library REST Web Services, 187 Java clients before calling Web Services, 55 calling Web Services, 53 CookieContainer, 54, 55, 59, 60 deserializing content, 61 dynamic Web Service calls, 60 security, 53 serializing content, 61 static Web Service calls, 58, 60 transactions, 54 two ways to call Web Services, 58 JAX-RPC, 14 deployment descriptor, 22 mapping file, 22 JMS Web Services, 27 MessageImporter component, 28 Patch Bay configuration, 28 JSON markup for parameters, 130 JSON output, 135
O
operations repository items, 79 output markup REST Web Services, 134
P
parameters control, 125 functional, 127 JSON markup, 130 message body, 128 URL query string markup, 131 XML markup, 130 Patch Bay configuration for JMS Web Services, 28 persistent cache. See Integration Data repository positional parameters, 127 POST method handling as other methods, 120 properties returning for form handlers, 157 property aliasing, 176 property filtering, 171 propertyElementNameSeparator, 45
L
logging in as internal user, 122 external users, 121 to the REST Web Services server, 120 logging out of the REST Web Services server, 124
Q
queries executeQuery operation, 90 Integration Repository, 89 query string parameters, 128 query tag, 100
M
mapping files DTD, 38 example, 39 repository to XML data binding, 38 MappingRepositoryItem, 88 maxDepthAllowed, 177 message body parameters, 128 Content-Type, 129 MessageImporter component, 28 methods invoking with the REST Web Services, 153 multiple values in REST Web Services output, 138 JSON input for, 133 replacing in a repository item property, 133
R
Remote Procedure Calls, 107 APIs, 107 exception handling, 110 removeItem operations, 93 remove-item tag, 102 RemoveService, 51 removing repository items, 51 repositories REST path for, 117 repository item properties appending values, 132 replacing multiple values, 133 retrieving, 162 repository items adding, 164 deleting, 168 generating from XML documents, 48 listing, 159
N
namespaces XML Schema, 47
210
Index
REST Web Services, 159 retrieving, 160 setting properties, 166 transforming into XML documents, 46 transient, 166 repository to XML data binding, 37 mapping files, 38 XML Schemas, 43 repository to XML mapping files DTD, 38 example, 39 repository Web Services, 31 limitations, 32 Repository XML schema generating, 62 mapping file, 62 RepositoryItems deserializing, 61, 70 serializing, 61, 70 Web Service calls from Java clients, 66 Web Service calls from Java clients, 54 XML schema for Web Service calls, 59 RepositoryService class, 34 REST Nucleus components, 113 REST module Starting, 116 REST Web Services, 115 ATG client libraries, 118, 187 client software, 118 configuring the server, 177 control parameters, 125 functional parameters, 127 identifying a response, 137 input values, 131 output markup, 134 property aliasing, 176 property filtering, 171 repository items, 159 returned data, 134 security, 181 return depth, 143 returnFormHandlerExceptionsByDefault, 177 returnFormHandlerPropertiesByDefault, 178 RPCs. See Remote Procedure Calls RQL queries, 163
sessions sharing (.NET clients), 54, 66 showRestPaths, 178 static Web Service calls, 58 creating and compiling stubs, 59 creating and compiling the client, 59 distinction from dynamic calls, 58 WSDL, 59 status codes, HTTP, 134 stubs. See client stubs for .NET, See client stubs
U
updateItem operations, 91 derived properties, 92 UpdateService, 49 data validation, 49 updating repository items from XML documents, 49 URL parameters, 128 URL query string markup for parameters, 131 URLs REST Web Services, 116
V
validating data AddService, 48 UpdateService, 49
W
Web Service security, 22 NucleusSecurityManager, 23 NucleusSecurityRepository, 23 Web Services Administration UI, 15, 27, 31 ATG Web Services, 10, 24 before calling from .NET, 67 before calling from Java clients, 55 calling from .NET clients, 65, 68 calling from Java clients, 53, 58, 60 client stubs for .NET, 66 custom Web Services, 13 deploying, 24 generating, 14 infrastructure, 9 JMS messages, 27 limitations, 14 managing, 25 naming restrictions, 17 Nucleus component methods, 16 overview, 13 repository items, 31 REST, 115 runtime classes, 22 security, 14, 53, 54, 65, 66 transactions, 54, 66 wizard, 15, 27
S
Scenario Manager receiving messages from JMS Web Services, 29 SchemaManager component, 44 security REST Web Services, 181 Serializing content on the client side, 61, 70 service endpoint interface, 18 service interface class, 18 session identifiers for REST Web Services session, 120 session sharing example, 59, 60, 69
211
Index
web.xml files, 19 WSDL documents, 18
X
XML documents generating from repository items, 46 transforming into repository items, 48 updating repository items, 49
XML markup for parameters, 130 XML output, 136 XML SchemaManager component, 44 XML Schemas for Web Services, 61 generation utility, 43 itemRef attribute, 45 namespace, 47 references to other repository items, 45 repository to XML data binding, 43
212
Index

Ws Frame Guide

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Ws Frame Guide

Hochgeladen von

Copyright:

Verfügbare Formate

Version 10.0.

2 Web Services and Integration Framework Guide

Oracle ATG One Main Street Cambridge, MA 02142 USA

Web Services and Integration Framework Guide Document Version

ATG Web Services and Integration Framework Guide

Part I: Creating and Using Web Services in the ATG Platform

Creating Custom Web Services

Creating JMS Web Services

Creating Repository Web Services

ATG Web Services and Integration Framework Guide

Repository to XML Data Binding

Accessing ATG Web Services from Java Clients

Accessing ATG Web Services from .NET Clients

ATG Web Services and Integration Framework Guide

Complex Type Class NoSuchPropertyException Class RepositoryItemSerializer Class RepositoryItemSerializationException Class

Part II: Integration Framework

Using the Integration Repository

Remote Procedure Calls

ATG Web Services and Integration Framework Guide

107 108 109 109 110 110

ATG Web Services and Integration Framework Guide

10 Working with Component Properties

11 Invoking Component Methods 12 Invoking Form Handlers

13 Working with Repositories

15 Configuring the REST Server

ATG Web Services and Integration Framework Guide

16 Security for REST Web Services

17 ATG Client Libraries

ATG Web Services and Integration Framework Guide

Part I: Creating and Using Web Services in the ATG Platform

ATG Web Services and Integration Framework Guide

Web Application Generic Repository Services

ATG Web Services and Integration Framework Guide

- calculateOrderPrice - calculateOrderPriceSummary - calculateItemPriceSummary

- grantPromotion - revokePromotion - claimCoupon - getPromotionsAsXML

- getInventory - getInventoryStatus - setStockLevel - setStockLevels

- getProductXMLById - getProductXMLByDescription - getProductXMLByRQL - getProductSkusXML - catalogItemViewed

- setDefaultShippingAddress - setDefaultBillingAddress - setDefaultCreditCard - getDefaultShippingAddress - getDefaultBillingAddress - getDefaultCreditCard

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

1 Creating Custom Web Services

Overview of ATG Web Services Support

ATG Web Services and Integration Framework Guide

Automatic Generation of Web Services

Session and Security Support

ATG Web Services and Integration Framework Guide

Web Service Creation Wizard

Using the Wizard

ATG Web Services and Integration Framework Guide

ATG Web Services and Integration Framework Guide

Anatomy of a Web Service

ATG Web Services and Integration Framework Guide

Service Endpoint Interface and Implementation Class

ATG Web Services and Integration Framework Guide

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

<servlet> <servlet-name>getOrderStatus</servlet-name> <display-name>getOrderStatus</display-name> <servlet-class>com.sun.xml.rpc.server.http.JAXRPCServlet</servlet-class>

ATG Web Services and Integration Framework Guide

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

Handling Imported WSDL Documents

is mapped to a parent directory that has subdirectories holding WSDL documents.

<filter> <filter-name>WSDLImportFilter</filter-name> <filter-class>atg.webservice.WSDLImportFilter</filter-class> </filter> ... <filter-mapping> <filter-name>WSDLImportFilter</filter-name>

ATG Web Services and Integration Framework Guide

Web Service Registrar