You use the updateItem() method of the atg.repository.xml.UpdateService class to modify a repository item. For example, the following instance document updates a user’s email address:

<user:user xmlns:user="http://www.atg.com/ns/UserProfiles/user"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.atg.com/ns/UserProfiles/user
 UserProfiles+user.xsd " ID="user747">
 <user:user.emailAddress>sandy@example.com</user:user.emailAddress>
</user:user>

The updateItem() method can optionally validate the instance document against the specified Schema. The logic for this is similar to the AddService.addItem() method: the UpdateService component has a validate property whose default value is false, and the updateItem() method can take a Boolean argument that overrides the value of the validate property.

Selecting the Item to Update

There are two ways to select the item to update:

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>

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 item’s dateOfBirth property to the name birthday, like this:

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

The corresponding instance document might look like this:

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

To specify this property in matchProperties, you use the name of the property as it is defined in the repository (dateOfBirth), not the target name (birthday). For example:

String[] matchProperties = {"dateOfBirth"};

You can configure the UpdateService to add a repository item if an attempt to update does not find a match. If you want the UpdateService to add items when no items are matched, set the addWhenNoMatchedItems property of the UpdateService to true.

If the property being updated is a simple type (such as a String), then its value is updated by the UpdateService. When the property being updated is a list, map or array, then the old value is replaced by the new value. The new value is not appended to the old value. If the property being updated is an item descriptor, then the appropriate fields of the existing item descriptors are updated.

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.