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
cascadeattribute 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 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"> </item-descriptor> </property> <property name="slotInstances" include="false"/> <property name="scenarioInstances" include="false"/> <property name="mailings" include="false"/> <property name="scenarioValues" include="false"/> <property name="firstName" targetName="first_name"/> </item-descriptor>
The data binding services all work with a single item descriptor and its properties (including any other item descriptors that are properties of the main item descriptor). The mapping file uses the item-descriptor tag to specify the repository and item descriptor that the mapping file is associated with:
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="user"
default-include="true">
The default-include attribute specifies whether the item’s properties should be included or excluded by default. This value can be overridden for individual properties. In this mapping file, various scenario-related properties are excluded:
<property name="slotInstances" include="false"/>
<property name="scenarioInstances" include="false"/>
<property name="mailings" include="false"/>
<property name="scenarioValues" include="false"/>
If a property is an item descriptor, there must be an item-descriptor tag inside the property tag. For example, the homeAddress property points to a contactInfo item descriptor:
<property name="homeAddress" include="true">
<item-descriptor
repository-path="/atg/userprofiling/ProfileAdapterRepository"
name="contactInfo"
default-include="false">
</item-descriptor>
</property>
Note that the item-descriptor tag for contactInfo can have property tags within it. The nesting of property tags and item-descriptor tags must reflect the hierarchy of the item descriptors in the repository. If you do not include a property tag for a property that points to an item descriptor (such as the homeAddress property shown above), the 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"/>
